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.
Format
Section titled “Format”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) |
How and / or logic works
Section titled “How and / or logic works”Each filter carries its own logic prefix; there is no global “AND mode” or “OR mode”.
- Filters prefixed with
andmust all match (like SQLAND). - Filters prefixed with
ormatch if any one of them is true (like SQLOR). - When mixing both: all
andfilters must pass and at least oneorfilter 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 |
Filterable fields
Section titled “Filterable fields”| 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 |
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) |
Text operators
Section titled “Text operators”| 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.
Numeric operators
Section titled “Numeric operators”| Operator | Description |
|---|---|
eq |
Equals |
neq |
Not equals |
gt |
Greater than |
gte |
Greater than or equal |
lt |
Less than |
lte |
Less than or equal |
Array operators (for tags)
Section titled “Array operators (for tags)”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 |
Location operators (for location)
Section titled “Location operators (for location)”| 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 |
Custom attributes
Section titled “Custom attributes”Use attr:field_name as the field:
?filter=and.eq.attr:cuisine.Italian?filter=and.eq.attr:cuisine.italianText 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.100filter=and.gte.attr:employees.1e2filter=and.eq.attr:active.trueExamples
Section titled “Examples”# 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.ItalianSDK compatibility for empty values
Section titled “SDK compatibility for empty values”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).