# 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](/api/contact#show-contacts-of-a-list): `GET /lists/{list_id}/contacts` | query parameter |
| [Show contacts of a segment](/api/contact#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](/api/contact#create-a-contacts-export): `POST /lists/{list_id}/exports` | query parameter |
| [Tag multiple contacts](/api/contact#tags-multiple-contacts): `POST /lists/{list_id}/contacts/tag` | body field |
| [Untag multiple contacts](/api/contact#untags-multiple-contacts): `POST /lists/{list_id}/contacts/untag` | body field |
| [Add interests to contacts](/api/contact#add-interest-s-to-contact-s): `POST /lists/{list_id}/contacts/add-interests` | body field |
| [Remove interests from contacts](/api/contact#remove-interest-s-from-contact-s): `POST /lists/{list_id}/contacts/remove-interests` | body field |
| [Create a segment](/api/segment#create-a-segment): `POST /lists/{list_id}/segments` | body field |
| [Update a segment](/api/segment#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:

```json
{"eq": {"status": "active"}}
```

To combine conditions, use `and` or `or`, whose value is a list of filters. Each item is itself a filter, so
they nest:

```json
{
  "and": [
    {"eq": {"status": "active"}},
    {"tagged": {"tag": "vip"}},
    {"or": [
      {"eq": {"country": "CA"}},
      {"eq": {"country": "FR"}}
    ]}
  ]
}
```

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 as `active` or `unsubscribed`.
- `registered`: the date and time the contact was added to the list. Responses call this date `subscribed_on`,
  but a filter must use `registered`.
- `id`: the contact's ID.
- Any custom attribute of the list, by its name, such as `country` or `birthday`.

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`:

```shell
curl --get \
  --url "https://api.cakemail.dev/lists/[list id]/contacts" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --data-urlencode 'json={"and":[{"eq":{"status":"active"}},{"tagged":{"tag":"vip"}}]}'
```

```python
import json
import requests

url = f"https://api.cakemail.dev/lists/{list_id}/contacts"

json_filter = {"and": [{"eq": {"status": "active"}}, {"tagged": {"tag": "vip"}}]}

headers = {
    "accept": "application/json",
    "authorization": f"Bearer {token}"
}

response = requests.get(url, params={"json": json.dumps(json_filter)}, headers=headers)

print(response.text)
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$filter = ['and' => [
  ['eq' => ['status' => 'active']],
  ['tagged' => ['tag' => 'vip']],
]];

$response = $client->request('GET', "https://api.cakemail.dev/lists/{$listId}/contacts", [
  'query' => ['json' => json_encode($filter)],
  'headers' => [
    'accept' => 'application/json',
    'authorization' => "Bearer {$token}"
  ],
]);

echo $response->getBody();
```

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:

```shell
curl --request POST \
  --url "https://api.cakemail.dev/lists/[list id]/contacts/tag" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"tags":["inactive"],"json":{"notopen":{"mailings":"PAST(6 month)"}}}'
```

This creates a segment of the contacts added in the last 30 days:

```shell
curl --request POST \
  --url "https://api.cakemail.dev/lists/[list id]/segments" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"name":"New this month","json":{"less_than_time_ago":{"registered":"30 day"}}}'
```

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
  example `mailings` with `eq`, or `link` with `open`.
- `` Invalid link id `<value>` ``: a `link` isn't a positive whole number.
- `Invalid JSON expression`: any other problem, such as a date value that isn't `"<n> <unit>"` or a `mailings`
  value with `FUTURE(...)`.

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.
