Filter Contacts with WQL

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.

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Filter Contact Params

Request schema for filtering Contacts with WQL.

filter
array of objects
length ≥ 0

Apply multiple filters to the result set using AND logic

filter
integer
≤ 500
Defaults to 50

Limit the number of results

integer
Defaults to 0

Offset the results

sort
array of objects
length ≥ 0

Sort by multiple resources and their columns

sort
Responses

Callback
Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json