curl -X POST "https://api.tracklysms.com/api/v2/audiences" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA"
},
{
"condition_type": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile"
},
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days"
}
]
}
}'
import requests
response = requests.post(
"https://api.tracklysms.com/api/v2/audiences",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
json={
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA",
},
{
"condition_type": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile",
},
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
},
],
},
},
)
data = response.json()
print(f"Created audience: {data['audience']['id']}")
const response = await fetch("https://api.tracklysms.com/api/v2/audiences", {
method: "POST",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "California T-Mobile Users",
description: "Contacts in CA on T-Mobile who clicked recently",
source_lists: [101],
filter: {
operator: "AND",
conditions: [
{
condition_type: "custom_field",
field: "state",
operator: "eq",
value: "CA",
},
{
condition_type: "carrier",
field: "carrier",
operator: "eq",
value: "T-Mobile",
},
{
condition_type: "time",
field: "last_clicked_at",
operator: "within",
value: 14,
unit: "days",
},
],
},
}),
});
const data = await response.json();
console.log(`Created audience: ${data.audience.id}`);
{
"success": true,
"audience": {
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA",
"unit": null,
"listId": null
},
{
"conditionType": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile",
"unit": null,
"listId": null
},
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
"listId": null
}
],
"groups": []
},
"cached_size": null,
"cached_size_updated_at": null,
"status": "active",
"created_at": "2025-11-20T10:15:00"
}
}
{
"error": "name is required",
"code": "missing_name"
}
{
"error": "Invalid condition_type: invalid",
"code": "invalid_condition_type"
}
{
"error": "Source list not found: 999",
"code": "source_list_not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Audiences (v2)
Create Audience
Create a new audience segment with filter conditions.
POST
/
v2
/
audiences
curl -X POST "https://api.tracklysms.com/api/v2/audiences" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA"
},
{
"condition_type": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile"
},
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days"
}
]
}
}'
import requests
response = requests.post(
"https://api.tracklysms.com/api/v2/audiences",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
json={
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA",
},
{
"condition_type": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile",
},
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
},
],
},
},
)
data = response.json()
print(f"Created audience: {data['audience']['id']}")
const response = await fetch("https://api.tracklysms.com/api/v2/audiences", {
method: "POST",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "California T-Mobile Users",
description: "Contacts in CA on T-Mobile who clicked recently",
source_lists: [101],
filter: {
operator: "AND",
conditions: [
{
condition_type: "custom_field",
field: "state",
operator: "eq",
value: "CA",
},
{
condition_type: "carrier",
field: "carrier",
operator: "eq",
value: "T-Mobile",
},
{
condition_type: "time",
field: "last_clicked_at",
operator: "within",
value: 14,
unit: "days",
},
],
},
}),
});
const data = await response.json();
console.log(`Created audience: ${data.audience.id}`);
{
"success": true,
"audience": {
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA",
"unit": null,
"listId": null
},
{
"conditionType": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile",
"unit": null,
"listId": null
},
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
"listId": null
}
],
"groups": []
},
"cached_size": null,
"cached_size_updated_at": null,
"status": "active",
"created_at": "2025-11-20T10:15:00"
}
}
{
"error": "name is required",
"code": "missing_name"
}
{
"error": "Invalid condition_type: invalid",
"code": "invalid_condition_type"
}
{
"error": "Source list not found: 999",
"code": "source_list_not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Creates a new audience with the specified filter definition. The audience size is not calculated at creation time — use the Get Audience Size endpoint to trigger a size calculation.
Body Parameters
string
required
Name of the audience. Maximum 255 characters.
string
Optional description for the audience. Maximum 1000 characters. A longer value currently returns a
500 error rather than a validation error.array of integers
Sending list IDs to scope this audience to. If omitted or empty, the audience will include contacts from all lists.
object
required
Filter group definition. See the Audience Filter DSL reference for the full specification.
Response Fields
boolean
true if the audience was created successfully.object
The full audience object.
Show Audience object properties
Show Audience object properties
string
Unique audience identifier.
string
Audience name.
string
Audience description.
array of integers
Sending list IDs this audience is scoped to.
object
The filter group definition. Condition objects in responses use camelCase keys (e.g.
conditionType).integer
Audience size.
null until calculated via the Get Audience Size endpoint.datetime
Timestamp of last size calculation.
null until calculated.string
Audience status:
active.datetime
Timestamp when the audience was created.
Examples
curl -X POST "https://api.tracklysms.com/api/v2/audiences" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA"
},
{
"condition_type": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile"
},
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days"
}
]
}
}'
import requests
response = requests.post(
"https://api.tracklysms.com/api/v2/audiences",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
json={
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA",
},
{
"condition_type": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile",
},
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
},
],
},
},
)
data = response.json()
print(f"Created audience: {data['audience']['id']}")
const response = await fetch("https://api.tracklysms.com/api/v2/audiences", {
method: "POST",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "California T-Mobile Users",
description: "Contacts in CA on T-Mobile who clicked recently",
source_lists: [101],
filter: {
operator: "AND",
conditions: [
{
condition_type: "custom_field",
field: "state",
operator: "eq",
value: "CA",
},
{
condition_type: "carrier",
field: "carrier",
operator: "eq",
value: "T-Mobile",
},
{
condition_type: "time",
field: "last_clicked_at",
operator: "within",
value: 14,
unit: "days",
},
],
},
}),
});
const data = await response.json();
console.log(`Created audience: ${data.audience.id}`);
{
"success": true,
"audience": {
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "California T-Mobile Users",
"description": "Contacts in CA on T-Mobile who clicked recently",
"source_lists": [101],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "custom_field",
"field": "state",
"operator": "eq",
"value": "CA",
"unit": null,
"listId": null
},
{
"conditionType": "carrier",
"field": "carrier",
"operator": "eq",
"value": "T-Mobile",
"unit": null,
"listId": null
},
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
"listId": null
}
],
"groups": []
},
"cached_size": null,
"cached_size_updated_at": null,
"status": "active",
"created_at": "2025-11-20T10:15:00"
}
}
{
"error": "name is required",
"code": "missing_name"
}
{
"error": "Invalid condition_type: invalid",
"code": "invalid_condition_type"
}
{
"error": "Source list not found: 999",
"code": "source_list_not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | missing_name | The name field was not provided |
| 400 | missing_filter | The filter field was not provided |
| 400 | name_too_long | Name exceeds 255 characters |
| 400 | source_list_not_found | A sending list ID in source_lists does not exist |
| 400 | invalid_group_operator | Filter group operator must be AND or OR |
| 400 | empty_filter_group | Filter group contains no conditions or nested groups |
| 400 | invalid_condition_type | Condition type is not one of the seven valid types |
| 400 | invalid_time_field | Time condition field is not valid |
| 400 | invalid_time_operator | Time condition operator is not valid |
| 400 | invalid_time_unit | Time condition unit must be days, hours, or minutes |
| 400 | missing_time_value | Time condition is missing value or unit |
| 400 | invalid_count_field | Count condition field is not valid |
| 400 | invalid_count_operator | Count condition operator is not valid |
| 400 | missing_count_value | Count condition is missing value |
| 400 | missing_custom_field_name | Custom field condition is missing field |
| 400 | invalid_custom_field_operator | Custom field condition operator is not valid |
| 400 | missing_custom_field_value | Custom field condition is missing value (and operator is not exists/not_exists) |
| 400 | invalid_carrier_operator | Carrier condition operator is not valid |
| 400 | missing_carrier_value | Carrier condition is missing value (and operator is not exists/not_exists) |
| 400 | invalid_timezone_operator | Timezone condition operator is not valid |
| 400 | missing_timezone_value | Timezone condition is missing value |
| 400 | invalid_revenue_field | Revenue condition field is not valid |
| 400 | invalid_revenue_operator | Revenue condition operator is not valid |
| 400 | missing_revenue_value | Revenue condition is missing value |
| 400 | invalid_phone_numbers_operator | Phone numbers condition operator is not in or not_in |
| 400 | missing_phone_numbers_value | Phone numbers condition value is missing or an empty list |
| 401 | invalid_credentials | API key is missing or invalid |
| 403 | account_suspended | Your account is suspended. Resolve outstanding billing or contact support. |
| 429 | rate_limited | Request throttled; retry with exponential backoff after the window resets. |
Next Steps
Creating Audiences
Build audiences in the UI
Create Schedule
Schedule a campaign to your audience
⌘I