Skip to main content
POST
/
v2
/
audiences
curl -X POST "https://app.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"
        }
      ]
    }
  }'

{
  "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"
      },
      {
        "conditionType": "carrier",
        "field": "carrier",
        "operator": "eq",
        "value": "T-Mobile"
      },
      {
        "conditionType": "time",
        "field": "last_clicked_at",
        "operator": "within",
        "value": 14,
        "unit": "days"
      }
    ],
    "groups": []
  },
  "cached_size": null,
  "cached_size_updated_at": null,
  "status": "active",
  "created_at": "2025-11-20T10:15:00"
}
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

​
name
string
required
Name of the audience. Maximum 255 characters.
​
description
string
Optional description for the audience.
​
source_lists
array of integers
Sending list IDs to scope this audience to. If omitted or empty, the audience will include contacts from all lists.
​
filter
object
required
Filter group definition. See the Audience Filter DSL reference for the full specification.

​
Response Fields

The response is the full 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 in responses use camelCase keys (e.g. conditionType).
​
cached_size
integer
Audience size. null until calculated via the Get Audience Size endpoint.
​
cached_size_updated_at
datetime
Timestamp of last size calculation. null until calculated.
​
status
string
Audience status: active.
​
created_at
datetime
Timestamp when the audience was created.

​
Examples

curl -X POST "https://app.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"
        }
      ]
    }
  }'

{
  "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"
      },
      {
        "conditionType": "carrier",
        "field": "carrier",
        "operator": "eq",
        "value": "T-Mobile"
      },
      {
        "conditionType": "time",
        "field": "last_clicked_at",
        "operator": "within",
        "value": 14,
        "unit": "days"
      }
    ],
    "groups": []
  },
  "cached_size": null,
  "cached_size_updated_at": null,
  "status": "active",
  "created_at": "2025-11-20T10:15:00"
}

​
Error Codes

HTTP StatusError CodeDescription
400missing_nameThe name field was not provided
400missing_filterThe filter field was not provided
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 (and operator is not exists/not_exists)
400invalid_carrier_operatorCarrier condition operator is not valid
400missing_carrier_valueCarrier condition is missing value (and operator is not exists/not_exists)
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

​
Next Steps

Creating Audiences

Build audiences in the UI

Create Schedule

Schedule a campaign to your audience