Filters contacts in an organization using Whippy Query Language (WQL).
Use this endpoint for complex audience-style filters across contacts and related resources
(messages, conversations, tags, segments, custom data, and more).
Contact dates of birth are stored on the embedded birth_date object and are queried
through the birth_date.day, birth_date.month, and birth_date.year columns.
The contact timestamp column is inserted_at.
Filter value shapes (pass bare JSON — never wrap as {"value": ...},
{"values": [...]}, or {"scalar": ...}):
==/!=/</>/<=/>=: string, number, or booleanlike/ilike: plain string pattern such as"%Jack%"(nocast)in/not_in: JSON array such as["Interview", "Offer"]ilike_any/not_ilike_all: non-empty array of strings (nocast)between: array of exactly two values;in_radius/not_in_radius:
[longitude, latitude, meters]contains/not_contains/is_contained: object or homogeneous array
Comparison × custom-object property type (properties[].type):
- text:
==!=innot_inlikeilikenot_likenot_ilikeilike_anynot_ilike_all - number / float:
==!=<><=>=innot_inbetween - boolean:
==!=in - date:
==!=<><=>=betweeninnot_in - list:
containsnot_containsis_containedhas_anyhas_none(notin/==) - map:
containsnot_containsis_contained - contact.geo:
in_radius/not_in_radiuswith[longitude, latitude, meters]
When a filter item includes cast, its value must be a string — or, for list
comparisons such as in, not_in, and between, a list of strings, each validated
with the same rules. Each string is an ISO date/datetime, or (with
"from": "relative_datetime") a relative datetime expression such as
"+0d Europe/Dublin" — an offset (+0d is today, -1d is yesterday) followed by an
IANA timezone. Casting a relative datetime to day_number/month_number compares
against the day/month of the resolved date. For example, to find contacts whose
birthday is today:
{"filter": [{"resource": "contact", "column": "birth_date.day", "comparison": "==",
"value": "+0d Europe/Dublin", "cast": {"from": "relative_datetime", "to": "day_number"},
"and": [{"resource": "contact", "column": "birth_date.month", "comparison": "==",
"value": "+0d Europe/Dublin", "cast": {"from": "relative_datetime", "to": "month_number"}}]}]}Returns matching contacts with a total count. Supports limit (default 50, max 500),
offset, and sort.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
