Filter

All list endpoints (for example List campaigns or List black list numbers) accept an optional filter query parameter, which narrows down the records returned.

Syntax

The filter parameter is a JSON object, sent URL-encoded in the query string. Each key is a field name, and each value is the value to compare against:

filter={"state":"Active","dialer":{"mode":"Predictive"}}

When the object contains more than one key, all conditions must match (they are combined with AND). The filter can contain up to 2048 characters.

The fields that can be used are listed in the Filter fields section of each list endpoint. Using a field that isn't supported by the endpoint returns a 400 Bad Request error, which includes the list of valid fields.

Operators

By default, a key compares the field for equality. To use a different comparison, append one of the following suffixes to the field name:

Suffix	Meaning	Example
(none)	Equal to (see matching rules below)	{"state":"Active"}
_gt	Greater than	{"attempts_gt":1}
_gte	Greater than or equal to	{"startDate_gte":"2026-09-01"}
_lt	Less than	{"attempts_lt":3}
_lte	Less than or equal to	{"endedAt_lte":"2026-09-30T23:59:59"}
_ovl	The array field contains at least one of the values	{"tagIds_ovl":["TAG_ID_1","TAG_ID_2"]}
_ctn	The array field contains the value	{"callflowIds_ctn":"CALLFLOW_ID"}

Operators can be combined on the same field to define a range:

filter={"startedAt_gte":"2026-09-01","startedAt_lt":"2026-10-01"}

Matching rules

How a value is compared depends on the type of the field:

• Text fields (for example name or number): case-insensitive partial match. {"name":"sales"} matches a campaign named "Q3 Sales Follow-up". This is what makes partial number lookups like {"number":"555"} possible.
• Identifier fields (ids and fields ending in Id, such as phoneSystemId): exact match.
• Enum fields (for example state or status): exact, case-sensitive match against one of the documented values.
• Number fields (for example attempts): numeric comparison, typically combined with an operator.
• Boolean fields (for example isArchived): true or false.
• Date and timestamp fields: ISO 8601 strings, such as "2026-09-01" or "2026-09-01T08:30:00". Timezone offsets are ignored.

Matching any of several values

When the value is an array and no operator suffix is used, the field must match any of the values in the array:

filter={"status":["NotContacted","RetryPending"]}

The special ids field works the same way, and is the easiest way to fetch several records by ID in a single request:

filter={"ids":["01a0dedd-b9a2-729d-8e0a-4e3ad9197aea","01a0dad2-c0a6-7205-8d4e-a2d5f4197825"]}

An empty array doesn't filter anything.

Nested objects

Some fields are objects. To filter on a property of the object, send a nested object with the properties you want to match. Nested properties are compared exactly:

filter={"dialer":{"mode":"Power"}}

Operator suffixes can only be used on top-level fields, not inside nested objects.

Default filters

Some endpoints apply a default filter when the filter parameter is sent. For example, when you send a filter to List campaigns, even an empty one ({}), archived campaigns are excluded, unless the filter includes the isArchived field. When the filter parameter is omitted, no default filter is applied, and archived campaigns are included. Default filters are described on each endpoint's page.

Encoding

Remember to URL-encode the filter value. With cURL, the easiest way is to combine -G with --data-urlencode, as shown in the examples. The code samples for the other languages use the standard URL-encoding helpers of each language.