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.
Filter Group Structure A filter group combines conditions with a logical operator.
{ "operator" : "AND" | "OR" , "conditions" : [ ... ], "groups" : [ ... ] }
Field Type Required Description operatorstring Yes Logical operator: AND or OR conditionsarray No Array of condition objects groupsarray 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.
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_atTimestamp of the contact’s most recent click last_sent_atTimestamp of the most recent message sent to the contact signup_dateTimestamp when the contact was added
Valid Operators: Operator Description Requires value + unit withinField date is within the last N units Yes not_withinField date is NOT within the last N units Yes beforeField date is before N units ago Yes afterField date is after N units ago Yes existsField has any value (is not null) No not_existsField is null or missing No
Valid Units: days, hours, minutesThe 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_countTotal number of messages sent to the contact click_countTotal number of clicks by the contact conversion_countTotal number of conversions attributed to the contact
Valid Operators: Operator Description gtGreater than gteGreater than or equal to ltLess than lteLess than or equal to eqEqual to neNot 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 eqEqual to Yes neNot equal to Yes inMatches any value in an array Yes (array) not_inDoes not match any value in an array Yes (array) containsField value contains the substring Yes gtGreater than (numeric fields) Yes gteGreater than or equal to (numeric fields) Yes ltLess than (numeric fields) Yes lteLess than or equal to (numeric fields) Yes existsField has any value No not_existsField 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: carrierValid Operators: Operator Description Requires value eqEqual to a single carrier Yes inMatches any carrier in an array Yes (array) existsCarrier data is present No not_existsCarrier 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: timezoneValid Operators: Operator Description eqEqual to a single timezone inMatches 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_revenueBoolean — whether the contact has any revenue revenue_totalTotal revenue amount attributed to the contact
Valid Operators: Operator Description eqEqual to gteGreater than or equal to lteLess than or equal to gtGreater than ltLess than
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_filterNo filter object was provided invalid_group_operatoroperator must be AND or ORempty_filter_groupGroup has no conditions and no nested groups invalid_condition_typecondition_type is not one of the six valid typesinvalid_time_fieldTime condition field is not valid invalid_time_operatorTime condition operator is not valid invalid_time_unitTime condition unit must be days, hours, or minutes missing_time_valueTime condition is missing value or unit invalid_count_fieldCount condition field is not valid invalid_count_operatorCount condition operator is not valid missing_count_valueCount condition is missing value missing_custom_field_nameCustom field condition is missing field invalid_custom_field_operatorCustom field condition operator is not valid missing_custom_field_valueCustom field condition is missing value invalid_carrier_operatorCarrier condition operator is not valid missing_carrier_valueCarrier condition is missing value invalid_timezone_operatorTimezone condition operator is not valid missing_timezone_valueTimezone condition is missing value invalid_revenue_fieldRevenue condition field is not valid invalid_revenue_operatorRevenue condition operator is not valid missing_revenue_valueRevenue condition is missing value
Next Steps
Creating Audiences Build audience segments in the UI
Create Audience Create an audience via the API
