Audience Filter DSL

The Audience Filter DSL is a structured query language used to define audience segments. Filters are passed as JSON objects when creating or updating audiences via the API. Every audience requires a filter group at the top level. Groups can contain conditions, nested groups, or both — enabling arbitrarily complex logic. A filter group combines conditions with a logical operator.

{
  "operator": "AND" | "OR",
  "conditions": [...],
  "groups": [...]
}

Field	Type	Required	Description
`operator`	string	Yes	Logical operator: `AND` or `OR`
`conditions`	array	No	Array of condition objects
`groups`	array	No	Array of nested filter groups

Every filter group must contain at least one condition or one nested group. An empty group will be rejected with the empty_filter_group error.

Condition Types

Each condition object must include a condition_type field that determines which fields and operators are valid.

Requests use the snake_case key condition_type. In API responses, condition objects are serialized with camelCase keys — conditionType, and (always present) listId. Optional keys joinOperator, secondaryOperator, secondaryValue, and secondaryUnit appear only when set.

1. Time Conditions

Filter contacts by time-based fields using relative or absolute time windows.

{
  "condition_type": "time",
  "field": "last_clicked_at",
  "operator": "within",
  "value": 7,
  "unit": "days"
}

Valid Fields:

Field	Description
`last_clicked_at`	Timestamp of the contact’s most recent click
`last_sent_at`	Timestamp of the most recent message sent to the contact
`signup_date`	Timestamp when the contact was added

Valid Operators:

Operator	Description	Requires `value` + `unit`
`within`	Field date is within the last N units	Yes
`not_within`	Field date is NOT within the last N units	Yes
`before`	Field date is before N units ago	Yes
`after`	Field date is after N units ago	Yes
`exists`	Field has any value (is not null)	No
`not_exists`	Field is null or missing	No

Valid Units: days, hours, minutes

The exists and not_exists operators do not require value or unit. All other operators require both.

2. Count Conditions

Filter contacts by numeric count fields such as send count, click count, or conversion count.

{
  "condition_type": "count",
  "field": "click_count",
  "operator": "gte",
  "value": 3
}

Valid Fields:

Field	Description
`send_count`	Total number of messages sent to the contact
`click_count`	Total number of clicks by the contact
`conversion_count`	Total number of conversions attributed to the contact

Valid Operators:

Operator	Description
`gt`	Greater than
`gte`	Greater than or equal to
`lt`	Less than
`lte`	Less than or equal to
`eq`	Equal to
`ne`	Not equal to

3. Custom Field Conditions

Filter contacts by any custom field stored on the contact record. Custom fields are arbitrary key-value pairs you define when creating or updating contacts.

{
  "condition_type": "custom_field",
  "field": "state",
  "operator": "eq",
  "value": "CA"
}

Valid Fields: Any custom field key that exists on your contacts. Valid Operators:

Operator	Description	Requires `value`
`eq`	Equal to	Yes
`ne`	Not equal to	Yes
`in`	Matches any value in an array	Yes (array)
`not_in`	Does not match any value in an array	Yes (array)
`contains`	Field value contains the substring	Yes
`gt`	Greater than (numeric fields)	Yes
`gte`	Greater than or equal to (numeric fields)	Yes
`lt`	Less than (numeric fields)	Yes
`lte`	Less than or equal to (numeric fields)	Yes
`exists`	Field has any value	No
`not_exists`	Field is null or missing	No

4. Carrier Conditions

Filter contacts by their mobile carrier.

{
  "condition_type": "carrier",
  "field": "carrier",
  "operator": "in",
  "value": ["T-Mobile", "AT&T"]
}

Valid Fields: carrier Valid Operators:

Operator	Description	Requires `value`
`eq`	Equal to a single carrier	Yes
`in`	Matches any carrier in an array	Yes (array)
`exists`	Carrier data is present	No
`not_exists`	Carrier data is missing	No

5. Timezone Conditions

Filter contacts by their timezone.

{
  "condition_type": "timezone",
  "field": "timezone",
  "operator": "in",
  "value": ["America/New_York", "America/Chicago"]
}

Valid Fields: timezone Valid Operators:

Operator	Description
`eq`	Equal to a single timezone
`in`	Matches any timezone in an array

Timezone values use the IANA timezone database format (e.g., America/New_York, US/Pacific, Europe/London).

6. Revenue Conditions

Filter contacts by revenue data.

{
  "condition_type": "revenue",
  "field": "revenue_total",
  "operator": "gte",
  "value": 10.00
}

Valid Fields:

Field	Description
`has_revenue`	Boolean — whether the contact has any revenue
`revenue_total`	Total revenue amount attributed to the contact

Valid Operators:

Operator	Description
`eq`	Equal to
`gte`	Greater than or equal to
`lte`	Less than or equal to
`gt`	Greater than
`lt`	Less than

7. Phone Numbers Conditions

Filter contacts by matching against an explicit list of phone numbers.

{
  "condition_type": "phone_numbers",
  "field": "phone",
  "operator": "in",
  "value": ["+15551234567", "+15559876543"]
}

The field key must be present on a phone_numbers condition. Its value is not used for matching, but the underlying model requires the field — omitting it currently causes a 500 error rather than a validation error. Send any non-empty string (e.g. "phone").

Valid Fields: The field value is not used for matching, but field must be present (any non-empty string). Valid Operators:

Operator	Description	Requires `value`
`in`	Contact’s phone number is in the provided list	Yes (non-empty array)
`not_in`	Contact’s phone number is not in the provided list	Yes (non-empty array)

value must be a non-empty array of phone numbers. An empty or missing list is rejected with missing_phone_numbers_value.

Nesting Groups

Groups can be nested to create complex boolean logic. Each nested group has its own operator and set of conditions. Example: Find contacts who were sent a message AND clicked within 30 days, AND whose carrier is either T-Mobile OR AT&T.

{
  "operator": "AND",
  "conditions": [
    {
      "condition_type": "time",
      "field": "last_clicked_at",
      "operator": "within",
      "value": 30,
      "unit": "days"
    },
    {
      "condition_type": "count",
      "field": "send_count",
      "operator": "gte",
      "value": 1
    }
  ],
  "groups": [
    {
      "operator": "OR",
      "conditions": [
        {
          "condition_type": "carrier",
          "field": "carrier",
          "operator": "eq",
          "value": "T-Mobile"
        },
        {
          "condition_type": "carrier",
          "field": "carrier",
          "operator": "eq",
          "value": "AT&T"
        }
      ]
    }
  ]
}

This evaluates as:

(last_clicked_at within 30 days AND send_count >= 1)
AND
(carrier = "T-Mobile" OR carrier = "AT&T")

You can nest groups multiple levels deep. There is no hard limit on nesting depth, but deeply nested filters will take longer to evaluate.

Validation Error Codes

If your filter is malformed, the API returns a 400 response with one of the following error codes:

Error Code	Description
`missing_filter`	No filter object was provided
`invalid_group_operator`	`operator` must be `AND` or `OR`
`empty_filter_group`	Group has no conditions and no nested groups
`invalid_condition_type`	`condition_type` is not one of the seven valid types
`invalid_time_field`	Time condition `field` is not valid
`invalid_time_operator`	Time condition `operator` is not valid
`invalid_time_unit`	Time condition `unit` must be `days`, `hours`, or `minutes`
`missing_time_value`	Time condition is missing `value` or `unit`
`invalid_count_field`	Count condition `field` is not valid
`invalid_count_operator`	Count condition `operator` is not valid
`missing_count_value`	Count condition is missing `value`
`missing_custom_field_name`	Custom field condition is missing `field`
`invalid_custom_field_operator`	Custom field condition `operator` is not valid
`missing_custom_field_value`	Custom field condition is missing `value`
`invalid_carrier_operator`	Carrier condition `operator` is not valid
`missing_carrier_value`	Carrier condition is missing `value`
`invalid_timezone_operator`	Timezone condition `operator` is not valid
`missing_timezone_value`	Timezone condition is missing `value`
`invalid_revenue_field`	Revenue condition `field` is not valid
`invalid_revenue_operator`	Revenue condition `operator` is not valid
`missing_revenue_value`	Revenue condition is missing `value`
`invalid_phone_numbers_operator`	Phone numbers condition `operator` is not `in` or `not_in`
`missing_phone_numbers_value`	Phone numbers condition `value` is missing or an empty list

API Reference

V2 API Reference

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Profiles (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

Filter Group Structure

Condition Types

1. Time Conditions

2. Count Conditions

3. Custom Field Conditions

4. Carrier Conditions

5. Timezone Conditions

6. Revenue Conditions

7. Phone Numbers Conditions

Nesting Groups

Validation Error Codes

Next Steps

Creating Audiences

Create Audience

​Filter Group Structure

​Condition Types

​1. Time Conditions

​2. Count Conditions

​3. Custom Field Conditions

​4. Carrier Conditions

​5. Timezone Conditions

​6. Revenue Conditions

​7. Phone Numbers Conditions

​Nesting Groups

​Validation Error Codes

​Next Steps

Creating Audiences

Create Audience

Filter Group Structure

Condition Types

1. Time Conditions

2. Count Conditions

3. Custom Field Conditions

4. Carrier Conditions

5. Timezone Conditions

6. Revenue Conditions

7. Phone Numbers Conditions

Nesting Groups

Validation Error Codes

Next Steps