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
string
required
The unique identifier of the audience to update.
Body Parameters
string
Updated audience name. Maximum 255 characters.
string
Updated audience description. Maximum 1000 characters. A longer value currently returns a
500 error rather than a validation error.array of integers
Updated sending list IDs to scope the audience. Empty array means all lists.
object
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).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 use camelCase keys (e.g.
conditionType).integer
Cached audience size. Reset to
null if filter was changed.datetime
Timestamp of last size calculation. Reset to
null if filter was changed.string
Audience status.
datetime
Timestamp when the audience was created.
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 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 |
| 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. |
| 429 | rate_limited | Request throttled; retry with exponential backoff after the window resets. |
| 404 | not_found | No audience exists with the specified ID |
Next Steps
Creating Audiences
Manage audience segments
Create Schedule
Schedule a campaign
⌘I