Skip to main content
POST
/
v4
/
subscribers
/
filter
Filter subscribers based on engagement
curl --request POST \
  --url https://api.kit.com/v4/subscribers/filter \
  --header 'Content-Type: application/json' \
  --header 'X-Kit-Api-Key: <api-key>' \
  --data '
{
  "all": [
    {
      "type": "opens",
      "count_greater_than": 5,
      "after": "2024-01-01",
      "before": "2024-12-31"
    },
    {
      "type": "clicks",
      "count_greater_than": 2,
      "after": "2024-01-01",
      "before": "2024-12-31",
      "any": [
        {
          "type": "urls",
          "urls": [
            "kit.com",
            "amazon.com"
          ],
          "matching": "contains"
        },
        {
          "type": "broadcasts",
          "ids": [
            1,
            2,
            3
          ]
        }
      ]
    }
  ]
}
'
{
  "subscribers": [
    {
      "id": "456",
      "first_name": "Jane",
      "email_address": "[email protected]",
      "created_at": "2024-12-01T15:45:00Z",
      "tag_names": [
        "newsletter",
        "engaged"
      ],
      "tag_ids": [
        "123",
        "456"
      ]
    },
    {
      "id": "789",
      "first_name": null,
      "email_address": "[email protected]",
      "created_at": "2024-11-15T10:00:00Z",
      "tag_names": [],
      "tag_ids": []
    }
  ],
  "pagination": {
    "has_previous_page": false,
    "has_next_page": true,
    "start_cursor": "WzQ1Nl0=",
    "end_cursor": "Wzc4OV0=",
    "per_page": 10,
    "total_count": 42
  }
}

Authorizations

X-Kit-Api-Key
string
header
required

Authenticate API requests via an API Key

Body

application/json

Filter subscribers based on engagement and subscription criteria using the 'all' array with filter conditions that must all be met (AND logic).

all
object[]
required

Array of filter conditions where ALL must be met (AND logic)

Response

Returns a list of subscribers matching the filters

subscribers
object[]
required
pagination
object
required