curl -X PUT "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "High-Value Clickers (Updated)",
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days"
},
{
"condition_type": "count",
"field": "click_count",
"operator": "gte",
"value": 5
}
]
}
}'
import requests
audience_id = "664f1a2b3c4d5e6f7a8b9c0d"
response = requests.put(
f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
json={
"name": "High-Value Clickers (Updated)",
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
},
{
"condition_type": "count",
"field": "click_count",
"operator": "gte",
"value": 5,
},
],
},
},
)
audience = response.json()
print(f"Updated: {audience['name']}")
const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";
const response = await fetch(
`https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
{
method: "PUT",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "High-Value Clickers (Updated)",
filter: {
operator: "AND",
conditions: [
{
condition_type: "time",
field: "last_clicked_at",
operator: "within",
value: 14,
unit: "days",
},
{
condition_type: "count",
field: "click_count",
operator: "gte",
value: 5,
},
],
},
}),
}
);
const audience = await response.json();
console.log(`Updated: ${audience.name}`);
{
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "High-Value Clickers (Updated)",
"description": "Contacts who clicked at least 3 times in the last 30 days",
"source_lists": [101, 102],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
"listId": null
},
{
"conditionType": "count",
"field": "click_count",
"operator": "gte",
"value": 5,
"unit": null,
"listId": null
}
],
"groups": []
},
"cached_size": null,
"cached_size_updated_at": null,
"status": "active",
"created_at": "2025-10-01T14:22:00"
}
{
"error": "Filter group must have at least one condition or nested group",
"code": "empty_filter_group"
}
{
"error": "Audience not found",
"code": "not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Audiences (v2)
Update Audience
Update an existing audience’s name, description, source lists, or filter.
PUT
/
v2
/
audiences
/
{id}
curl -X PUT "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "High-Value Clickers (Updated)",
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days"
},
{
"condition_type": "count",
"field": "click_count",
"operator": "gte",
"value": 5
}
]
}
}'
import requests
audience_id = "664f1a2b3c4d5e6f7a8b9c0d"
response = requests.put(
f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
json={
"name": "High-Value Clickers (Updated)",
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
},
{
"condition_type": "count",
"field": "click_count",
"operator": "gte",
"value": 5,
},
],
},
},
)
audience = response.json()
print(f"Updated: {audience['name']}")
const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";
const response = await fetch(
`https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
{
method: "PUT",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "High-Value Clickers (Updated)",
filter: {
operator: "AND",
conditions: [
{
condition_type: "time",
field: "last_clicked_at",
operator: "within",
value: 14,
unit: "days",
},
{
condition_type: "count",
field: "click_count",
operator: "gte",
value: 5,
},
],
},
}),
}
);
const audience = await response.json();
console.log(`Updated: ${audience.name}`);
{
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "High-Value Clickers (Updated)",
"description": "Contacts who clicked at least 3 times in the last 30 days",
"source_lists": [101, 102],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
"listId": null
},
{
"conditionType": "count",
"field": "click_count",
"operator": "gte",
"value": 5,
"unit": null,
"listId": null
}
],
"groups": []
},
"cached_size": null,
"cached_size_updated_at": null,
"status": "active",
"created_at": "2025-10-01T14:22:00"
}
{
"error": "Filter group must have at least one condition or nested group",
"code": "empty_filter_group"
}
{
"error": "Audience not found",
"code": "not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Updates the specified audience. All body parameters are optional — only the fields you include will be updated. If the
filter is changed, the cached_size is cleared and must be recalculated using the Get Audience Size endpoint.
Path Parameters
Body Parameters
Updated audience description. Maximum 1000 characters. A longer value currently returns a
500 error rather than a validation error.Updated filter group definition. See the Audience Filter DSL reference for the full specification. Changing the filter clears the cached audience size.
Response Fields
The response is the full updated audience object (flat, not wrapped).Examples
curl -X PUT "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "High-Value Clickers (Updated)",
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days"
},
{
"condition_type": "count",
"field": "click_count",
"operator": "gte",
"value": 5
}
]
}
}'
import requests
audience_id = "664f1a2b3c4d5e6f7a8b9c0d"
response = requests.put(
f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
json={
"name": "High-Value Clickers (Updated)",
"filter": {
"operator": "AND",
"conditions": [
{
"condition_type": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
},
{
"condition_type": "count",
"field": "click_count",
"operator": "gte",
"value": 5,
},
],
},
},
)
audience = response.json()
print(f"Updated: {audience['name']}")
const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";
const response = await fetch(
`https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
{
method: "PUT",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "High-Value Clickers (Updated)",
filter: {
operator: "AND",
conditions: [
{
condition_type: "time",
field: "last_clicked_at",
operator: "within",
value: 14,
unit: "days",
},
{
condition_type: "count",
field: "click_count",
operator: "gte",
value: 5,
},
],
},
}),
}
);
const audience = await response.json();
console.log(`Updated: ${audience.name}`);
{
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "High-Value Clickers (Updated)",
"description": "Contacts who clicked at least 3 times in the last 30 days",
"source_lists": [101, 102],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 14,
"unit": "days",
"listId": null
},
{
"conditionType": "count",
"field": "click_count",
"operator": "gte",
"value": 5,
"unit": null,
"listId": null
}
],
"groups": []
},
"cached_size": null,
"cached_size_updated_at": null,
"status": "active",
"created_at": "2025-10-01T14:22:00"
}
{
"error": "Filter group must have at least one condition or nested group",
"code": "empty_filter_group"
}
{
"error": "Audience not found",
"code": "not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 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 |
| 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 |
| 400 | invalid_carrier_operator | Carrier condition operator is not valid |
| 400 | missing_carrier_value | Carrier condition is missing value |
| 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. |
| 404 | not_found | No audience exists with the specified ID |
Next Steps
Creating Audiences
Manage audience segments
Create Schedule
Schedule a campaign