The Segmentation v1 API was deprecated on December 31, 2022. Following deprecation, all segments created in the Marketing Campaigns user interface began using the Segmentation v2 API.
To enable manual migration and data retrieval, the GET and DELETE v1 API endpoints will remain available. The POST (create) and PATCH (update) v1 endpoints were removed on January 31, 2023 because it is no longer possible to create new v1 segments or modify existing ones. See our Segmentation v1 to v2 upgrade instructions to manually migrate your segments to the v2 API.
Any numeric type that can be an integer or float.
Integer: [1-9][0-9]*
Float: [0-9]+.[0-9]+
A set of characters delimited by double or single quotes.
Escaping must be done for the character used as the delimiter if it is found within the string. The escape character is the backslash, \, which must also be escaped with a preceding \.
_10'Hello, World! It\'s a beautiful day'
When using the LIKE or NOT LIKE operators, The percentage symbol, %, will be interpreted as a wildcard character. To escape this character and not treat it as a wildcard, a second % should be used.
_10"email LIKE '%gmail.com'"
A timestamp whose literal value is formatted as a string in ISO 8601 format: YYYY-MM-DDTHH:mm:SSZ(-)HH:mm
A time interval with an integral scalar value and some unit of time, which can be one of the following: second, minute, hour, day, month, or year.
_10"10 day"
Boolean values are true or false.
Null is a special type that represents a lack of a value.
| Operator | Associativity | Operands |
|---|---|---|
| AND | Left | 2 |
| OR | Left | 2 |
| NOT | Right | 2 (binary) |
| NOT | Right | 1 (unary) |
Precedence from low to high:
| Operator | Associativity | Operands | Supported Types |
|---|---|---|---|
| - | Left | 2 (binary) | Numeric - Numeric DateTime - Interval |
| + | Left | 2 | Numeric + Numeric DateTime + Interval String + String (concatenation) |
| / | Left | 2 | Numeric / Numeric |
| * | Left | 2 | Numeric * Numeric |
| % | Left | 2 | Numeric % Numeric (modulo) |
| - | Left | 1 (unary) | - Numeric |
| Operator | Supported Types (T represents any type) |
|---|---|
| = | T = T |
| != | T != T |
| < | Numeric < Numeric DateTime < DateTime String < String |
> | Numeric < Numeric DateTime < DateTime String < String |
| <= | Numeric < Numeric DateTime < DateTime String < String |
| >= | Numeric < Numeric DateTime < DateTime String < String |
| LIKE/ NOT LIKE | String (NOT) LIKE String |
| IS (NOT) | T is (NOT) NULL |
| (NOT) IN | T IN (T) |
| (NOT) BETWEEN | Numeric (NOT) BETWEEN Numeric AND Numeric DateTime (NOT) BETWEEN DateTime AND DateTime String (NOT) BETWEEN String AND String |
Identifiers are named things within a given query. These include both function names and field/column names. Identifiers cannot be a keyword and must only allow the characters: [a-zA-Z_]+..
Identifiers that do not meet the previous format may still be used. However, they must be encapsulated within backticks. I.E. 000supercoolid
Functions can be invoked with or without parameters by providing the function name—remember, function names are identifiers—followed by a list of comma separated arguments enclosed in parentheses.
_10MY_FUNCTION(a,b,c)
These are functions that should be used consistently across consumers of the parser. Whether or not your implementation actually supports them is up to you.
_10CONTAINS(array_or_map, value_or_key)
Contains should return a boolean indicating the presence of a value in an array or map. When used with an array, true should be returned when the array holds the given value. When used with a map, true should be returned when the map has an element with the given key.
_10CONCAT(string_one,string_two)
Concat takes two strings, combines them as a single string in the order they are passed in, and returns the result.
_10LENGTH(string)
Length takes a single string and returns the number of characters in the string.
_10LOWER(string)
Lower returns a lowercase version of the given string.
_10NOW()
Returns the current date and time.
A number of fields are available on every contact. These include the strings:
alternate_emails
address_line_1
address_line_2
city
contact_id
country
created_at
email
phone_number_id
external_id
anonymous_id
email_domains
event_data
event_source
event_timestamp
event_type
first_name
list_ids
last_name
postal_code
state_province_region
updated_at
In the future, the address fields may be used with a third-party service to populate a location type field when contacts are added or updated. In addition, a contact's alternate_emails field represents a set of strings.
_10{_10 "name": "All Gmail Users",_10 "query_dsl": "email LIKE '%gmail.com'"_10}
_10{_10 "name": "My Favorite Zip Codes",_10 "query_dsl": "postal_code IN ('90124', '90125', '90126')"_10}
_10{_10 "name": "My Least Favorite Zip Codes",_10 "query_dsl": "postal_code NOT IN ('90124', '90125', '90126')"_10}
_10{_10 "name": "Everyone named Bob, BOB or bob",_10 "query_dsl": "lower(first_name) = 'bob'"_10}
_10{_10 "name": "All Delivered in Last 10 days",_10 "query_dsl": "(event_source = 'mail' AND event_type = 'delivered' AND event_timestamp >= (NOW() - interval 10 day))"_10}
_10{_10 "name": "All Delivered in Last 10 days",_10 "query_dsl": "(event_source = 'mail' AND event_type = 'delivered' AND event_timestamp BETWEEN TIMESTAMP '2019-08-07T18:00:00Z' AND TIMESTAMP '2019-08-08T18:00:00Z')"_10}
_10{_10"name": "My External ID Contacts",_10"query_dsl": "external_id LIKE '123%'"_10}