Filtering contacts with JSON
A JSON filter selects the contacts of a list that match conditions: a status, a tag, an interest, a custom attribute, a date, or what they did with your campaigns. The same filter works to list contacts, to export them, to tag them or set their interests in bulk, and to define a segment.
Where the filter goes
The filter is called json everywhere. It is a query parameter on requests that read or export contacts, and a
body field on requests that change them.
| Request | Where json goes |
|---|---|
Show contacts of a list: GET /lists/{list_id}/contacts | query parameter |
Show contacts of a segment: GET /lists/{list_id}/segments/{segment_id}/contacts | query parameter, combined with the segment's own conditions |
Create a contacts export: POST /lists/{list_id}/exports | query parameter |
Tag multiple contacts: POST /lists/{list_id}/contacts/tag | body field |
Untag multiple contacts: POST /lists/{list_id}/contacts/untag | body field |
Add interests to contacts: POST /lists/{list_id}/contacts/add-interests | body field |
Remove interests from contacts: POST /lists/{list_id}/contacts/remove-interests | body field |
Create a segment: POST /lists/{list_id}/segments | body field |
Update a segment: PATCH /lists/{list_id}/segments/{segment_id} | body field |
The query and fiql parameters that these requests also accept are deprecated: use json. Send only one of
the three in a request.
How a filter is built
A filter is a JSON object with exactly one key, the operator. The operator's value is the condition:
Code
To combine conditions, use and or or, whose value is a list of filters. Each item is itself a filter, so
they nest:
Code
This selects active contacts tagged vip whose country custom attribute is CA or FR.
An object with two keys is refused: write {"and": [{"eq": {"status": "active"}}, {"eq": {"country": "CA"}}]},
not {"eq": {"status": "active", "country": "CA"}}.
Attributes you can compare
The comparison and date operators take one {attribute: value} pair. The attribute is a column of the list:
email: the contact's email address.status: the contact's status in the list, such asactiveorunsubscribed.registered: the date and time the contact was added to the list. Responses call this datesubscribed_on, but a filter must useregistered.id: the contact's ID.- Any custom attribute of the list, by its name, such as
countryorbirthday.
Values are written as strings, numbers included: {"gt": {"age": "30"}}.
Operators
Compare an attribute
| Operator | Selects contacts whose attribute… | Example |
|---|---|---|
eq | equals the value | {"eq": {"status": "active"}} |
ne | differs from the value | {"ne": {"country": "CA"}} |
gt, ge | is greater than, or greater than or equal to, the value | {"gt": {"age": "30"}} |
lt, le | is less than, or less than or equal to, the value | {"le": {"registered": "2026-01-01"}} |
like | matches the pattern, where * stands for any characters | {"like": {"email": "*@example.com"}} |
unlike | doesn't match the pattern | {"unlike": {"email": "*@example.com"}} |
Tags and interests
| Operator | Selects contacts that… | Example |
|---|---|---|
tagged | have the tag | {"tagged": {"tag": "vip"}} |
nottagged | don't have the tag | {"nottagged": {"tag": "vip"}} |
interested | have the interest | {"interested": {"interest": "sports"}} |
notinterested | don't have the interest | {"notinterested": {"interest": "sports"}} |
Dates relative to now
The value is "<n> <unit>", where the unit is year, month, week, day, hour, minute or second.
| Operator | Selects contacts whose date attribute is… | Example |
|---|---|---|
less_than_time_ago | within the last <n> <unit> | {"less_than_time_ago": {"registered": "30 day"}} |
more_than_time_ago | older than <n> <unit> | {"more_than_time_ago": {"registered": "1 year"}} |
less_than_time_away | in the future, within the next <n> <unit> | {"less_than_time_away": {"renewal_date": "1 week"}} |
more_than_time_away | further in the future than <n> <unit> | {"more_than_time_away": {"renewal_date": "1 month"}} |
What contacts did with your campaigns
Each activity operator has a negative form with not in front: open and notopen, sent and notsent,
clicked and notclicked, bounced and notbounced, unsubscribed and notunsubscribed, complained and
notcomplained, engaged and notengaged, blocked and notblocked.
Its value names the campaigns, in one of three ways:
| Operand | Means | Example |
|---|---|---|
campaign | one campaign, by its ID | {"open": {"campaign": "123"}} |
mailings with PAST(<n> <unit>) | the campaigns sent in that past period | {"notopen": {"mailings": "PAST(6 month)"}} |
mailings with <YYYY-MM-DD>,<YYYY-MM-DD> | the campaigns sent between those dates | {"bounced": {"mailings": "2026-01-01,2026-06-30"}} |
clicked and notclicked also accept link, a link's ID: {"clicked": {"link": "456"}}.
mailings takes only a past period or a date range: FUTURE(...) is refused.
Send a filter in a query parameter
In a GET, and in POST /lists/{list_id}/exports, the filter is a JSON string in the json query parameter,
URL-encoded. Let your HTTP client do the encoding.
This lists the active contacts tagged vip:
Code
Code
Code
On a segment, the filter narrows the segment: GET /lists/{list_id}/segments/{segment_id}/contacts?json=...
returns the segment's contacts that also match the filter.
Send a filter in a request body
In the bulk requests and the segment requests, json is a field of the JSON body, written as an object, not as
a string.
This tags as inactive every contact that opened none of the campaigns of the last six months:
Code
This creates a segment of the contacts added in the last 30 days:
Code
In the tag, untag and interest requests, send either contact_ids or a filter, not both.
When a filter is refused
A filter that can't be read is answered with 400 Bad Request. The message says what is wrong:
Invalid condition: an object holds more than one key.Invalid operator: <name>: the operator doesn't exist.Invalid attribute `<name>` for operator `<operator>`: the attribute doesn't go with this operator, for examplemailingswitheq, orlinkwithopen.Invalid link id `<value>`: alinkisn't a positive whole number.Invalid JSON expression: any other problem, such as a date value that isn't"<n> <unit>"or amailingsvalue withFUTURE(...).
A request that sends more than one of query, fiql and json is refused too.
The full grammar is in the API reference, under the json parameter of each request listed above.