Skip to main content
PUT
/
v2
/
audiences
/
{id}
curl -X PUT "https://app.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
        }
      ]
    }
  }'
{
  "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"
      },
      {
        "conditionType": "count",
        "field": "click_count",
        "operator": "gte",
        "value": 5
      }
    ],
    "groups": []
  },
  "cached_size": null,
  "cached_size_updated_at": null,
  "status": "active",
  "created_at": "2025-10-01T14:22:00"
}
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

id
string
required
The unique identifier of the audience to update.

Body Parameters

name
string
Updated audience name. Maximum 255 characters.
description
string
Updated audience description.
source_lists
array of integers
Updated sending list IDs to scope the audience. Empty array means all lists.
filter
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).
id
string
Unique audience identifier.
name
string
Audience name.
description
string
Audience description.
source_lists
array of integers
Sending list IDs this audience is scoped to.
filter
object
The filter group definition. Condition objects use camelCase keys (e.g. conditionType).
cached_size
integer
Cached audience size. Reset to null if filter was changed.
cached_size_updated_at
datetime
Timestamp of last size calculation. Reset to null if filter was changed.
status
string
Audience status.
created_at
datetime
Timestamp when the audience was created.

Examples

curl -X PUT "https://app.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
        }
      ]
    }
  }'
{
  "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"
      },
      {
        "conditionType": "count",
        "field": "click_count",
        "operator": "gte",
        "value": 5
      }
    ],
    "groups": []
  },
  "cached_size": null,
  "cached_size_updated_at": null,
  "status": "active",
  "created_at": "2025-10-01T14:22:00"
}

Error Codes

HTTP StatusError CodeDescription
400name_too_longName exceeds 255 characters
400source_list_not_foundA sending list ID in source_lists does not exist
400invalid_group_operatorFilter group operator must be AND or OR
400empty_filter_groupFilter group contains no conditions or nested groups
400invalid_condition_typeCondition type is not one of the six valid types
400invalid_time_fieldTime condition field is not valid
400invalid_time_operatorTime condition operator is not valid
400invalid_time_unitTime condition unit must be days, hours, or minutes
400missing_time_valueTime condition is missing value or unit
400invalid_count_fieldCount condition field is not valid
400invalid_count_operatorCount condition operator is not valid
400missing_count_valueCount condition is missing value
400missing_custom_field_nameCustom field condition is missing field
400invalid_custom_field_operatorCustom field condition operator is not valid
400missing_custom_field_valueCustom field condition is missing value
400invalid_carrier_operatorCarrier condition operator is not valid
400missing_carrier_valueCarrier condition is missing value
400invalid_timezone_operatorTimezone condition operator is not valid
400missing_timezone_valueTimezone condition is missing value
400invalid_revenue_fieldRevenue condition field is not valid
400invalid_revenue_operatorRevenue condition operator is not valid
400missing_revenue_valueRevenue condition is missing value
401unauthorizedAPI key is missing or invalid
404not_foundNo audience exists with the specified ID

Next Steps

Creating Audiences

Manage audience segments

Create Schedule

Schedule a campaign