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 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --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": "jane@example.com",
      "created_at": "2024-12-01T15:45:00Z"
    }
  ],
  "pagination": {
    "has_previous_page": false,
    "has_next_page": false,
    "start_cursor": "WzQ1Nl0=",
    "end_cursor": "WzQ1Nl0=",
    "per_page": 100,
    "total_count": 1
  }
}

Authorizations

Authorization
string
header
required

Authenticate API requests via an OAuth token

Headers

Authorization
string
required

Query Parameters

per_page
integer
default:100

Number of results per page (max 100)

Required range: 1 <= x <= 100
after
string
before
string
include_total_count
boolean
default:false

Include total count of matching subscribers in response

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 filtered subscribers

subscribers
object[]
required
pagination
object
required