Skip to content

Filter Operators: Complete Reference

All list and export endpoints accept repeatable filter query parameters.

eq and neq compare exact, case-insensitive values. % and _ are literal characters with these operators. Numeric comparisons (gt, gte, lt, lte) require a finite numeric value and a numeric field (rating, score, review_count, or a numeric attr:<name>); invalid comparisons return 400 Bad Request.

Numeric fields (rating, score and review_count) validate decimal values for eq, neq, gt, gte, lt and lte, including exponent bounds supported by PostgreSQL. Non-finite, malformed or out-of-range values return 400 Bad Request. Other value operators are rejected on numeric fields; is_empty / is_not_empty check for null / non-null values.

filter=logic.operator.field.value
Part Values
logic and, or
operator See tables below
field Any lead field (see list below), or attr:name for custom attributes
value Filter value (omit for no-value operators like is_empty)

Each filter carries its own logic prefix; there is no global “AND mode” or “OR mode”.

  • Filters prefixed with and must all match (like SQL AND).
  • Filters prefixed with or match if any one of them is true (like SQL OR).
  • When mixing both: all and filters must pass and at least one or filter must pass.
Example Meaning
filter=and.eq.city.Paris city must be Paris
filter=and.eq.city.Paris&filter=and.gte.rating.4 city is Paris AND rating ≥ 4
filter=and.is_not_empty.email&filter=or.is_not_empty.phone has email OR has phone
Field Type Notes
name text
email text
phone text
city text
source text
source_id text
siren text Canonical 9-digit company identifier
website text
rating number
review_count integer Number of reviews
score number Computed score 0–100
tags array Use array operators
location location Use location operators
do_not_contact boolean eq / neq with true or false only (e.g. and.eq.do_not_contact.false before a campaign)
assignee email eq, neq or in with an email or me (a comma-separated list for in), or is_empty / is_not_empty. neq also returns unassigned leads: add and.is_not_empty.assignee to keep only assigned ones. An email that matches nobody is not an error: eq returns nothing and neq returns every lead. me is the caller; with an API key, it is the workspace owner. Example: and.eq.assignee.me for your leads.
attr:<name> varies Custom attribute (e.g., attr:cuisine)
Operator Description
eq Equals (exact, case-insensitive)
neq Not equals
contains Contains a literal substring, case-insensitive
not_contains Does not contain
starts_with Starts with
ends_with Ends with
is_empty Null or empty string
is_not_empty Not null and not empty
in Equals one of (comma-separated values, case-insensitive)

contains treats %, _ and backslashes as literal characters on standard text fields and text attributes. For example, contains.name.50% matches 50% off, not 500 off (URL-encode % as %25). This also applies to MCP list_leads.search. On standard text fields, not_contains, starts_with (and its alias prefix) and ends_with also treat %, _ and backslashes literally, with case-insensitive matching. NULL fields do not match either contains or not_contains.

Unknown operators, invalid attribute names and unsupported field/operator combinations return HTTP 400 instead of silently ignoring the filter. Attribute names must contain 1–100 ASCII letters, digits, underscores or hyphens. Custom attributes support eq, neq, gt, gte, lt, lte and contains; other operators on attributes return HTTP 400. Missing filter values and malformed filters also return HTTP 400. Empty strings remain valid text filter values.

in on standard text fields uses the same case-insensitive equality as eq, including PostgreSQL case normalization of every supplied value. %, _ and backslashes remain literal. NULL fields never match. An empty list (in.city.) matches nothing; an empty item in a nonempty list (in.city.,lyon) can match an empty string. Numeric and array fields do not gain text normalization.

If existing score or rating data cannot be serialized as JSON (for example, PostgreSQL NaN), JSON endpoints return HTTP 500 with code: "internal_error" and message: "Internal server error", rather than an empty HTTP 200 response. This includes the JSON export (explicit format=json or the default format): an error has no download attachment header. The value is not silently converted or changed in storage.

Operator Description
eq Equals
neq Not equals
gt Greater than
gte Greater than or equal
lt Less than
lte Less than or equal

Scalar eq and neq on tags return 400 Bad Request. Use array_contains or array_not_contains for membership; array equality is not supported.

Operator Description
array_contains Array contains value
array_not_contains Array does not contain value
array_empty Array is empty
array_not_empty Array is not empty
Operator Description Value format
within_radius Within N km of a point lat,lng,km
is_set Has coordinates None
is_not_set Missing coordinates None

Use attr:field_name as the field:

Terminal window
?filter=and.eq.attr:cuisine.Italian
?filter=and.eq.attr:cuisine.italian

Text attribute equality (eq and neq) is case-insensitive and treats % and _ literally. The examples above match a text attribute cuisine with value Italian.

Attribute comparisons use the stored type (text, number, or bool). Both JSON scalar values and legacy typed objects ({"text":"Lyon"}, {"number":100}, {"bool":true}) are supported. Text equality is case-insensitive and literal; numbers compare numerically (100, 100.0 and 1e2 are equal); booleans accept true / false, case-insensitively. An equality value that cannot represent a number or boolean does not match attributes of that type, but can match text.

gt, gte, lt and lte match only numeric attributes and use the same finite decimal validation as rating and score (invalid input returns HTTP 400). Null, malformed, list and object attribute values do not match positive comparisons. neq means no attribute with that name equals the value, so it also includes leads without that attribute; by contrast, neq on standard fields excludes NULL values. contains applies to text attributes only.

filter=and.eq.attr:employees.100
filter=and.gte.attr:employees.1e2
filter=and.eq.attr:active.true
Terminal window
# City = Athens AND rating >= 4
?filter=and.eq.city.Athens&filter=and.gte.rating.4
# Has email OR has phone
?filter=and.is_not_empty.email&filter=or.is_not_empty.phone
# Tagged as "restaurant"
?filter=and.array_contains.tags.restaurant
# Within 5km of Athens city center
# Value format: lat,lng,radius_km
?filter=and.within_radius.location.37.98,23.73,5
# Source is either "website" or "api"
?filter=and.in.source.website,api
# Leads with a custom "cuisine" attribute = Italian
?filter=and.eq.attr:cuisine.Italian

review_count is stored as an integer. It supports eq, neq, gt, gte, lt, lte, is_empty and is_not_empty. Comparison parameters use the same finite decimal validation as rating and score: eq.review_count.10.0 matches 10, while gt.review_count.10.5 matches integers of at least 11.

An empty text value must retain its final separator: and.contains.name. is valid, while and.contains.name is missing a value and returns HTTP 400 with an invalid filter message. Python now distinguishes an explicit empty string from an operator without a value. Go and TypeScript already preserve the empty segment. The frozen Rust SDK omits it: omit the optional filter when user input is empty, or use the REST API to express an explicit empty value. No Rust or Go SDK release or code change is included (ADR 0005).