SubscriberFilterRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/convertkit/main/json-schema/convertkit-subscriber-filter-request-schema.json",
  "title": "SubscriberFilterRequest",
  "description": "Filter subscribers based on engagement and subscription criteria using the 'all' array with filter conditions that must all be met (AND logic).",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/convertkit-subscribers-api-openapi.yml#/components/schemas/SubscriberFilterRequest",
  "type": "object",
  "properties": {
    "counting_mode": {
      "type": "string",
      "enum": [
        "raw",
        "unique_email"
      ],
      "description": "Controls how engagement-filter count thresholds are tallied. `raw` (default) counts every event — five opens of the same email = five. `unique_email` counts distinct emails on which the action occurred — five opens of the same email = one. Applies to every engagement filter (opens, clicks, sent, delivered) in the request; ignored for other filter types."
    },
    "all": {
      "type": "array",
      "description": "Array of filter conditions where ALL must be met (AND logic)",
      "items": {
        "$ref": "#/$defs/FilterCondition"
      }
    }
  },
  "required": [
    "all"
  ],
  "$defs": {
    "BroadcastAnyCondition": {
      "type": "object",
      "description": "Filter by specific broadcast IDs. Subscriber must have interacted with ANY of the specified broadcasts.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "broadcasts"
          ],
          "description": "Must be 'broadcasts'"
        },
        "ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Array of broadcast IDs. Subscriber must match ANY of these."
        }
      },
      "required": [
        "type",
        "ids"
      ]
    },
    "FilterCondition": {
      "type": "object",
      "description": "A filter condition with type and optional parameters. Used within the 'all' array for complex filtering where multiple conditions must be met.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "opens",
            "clicks",
            "sent",
            "delivered",
            "subscribed",
            "subscriber_state",
            "tags",
            "attribution"
          ],
          "description": "Type of filter condition. `attribution` matches subscribers by their *original signup attribution* — currently supports a `forms` sub-condition that matches by the form / landing-page id the subscriber signed up through. Attribution is the original signup source; it does not track current subscription state."
        },
        "count_greater_than": {
          "type": "integer",
          "description": "Minimum count (exclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')."
        },
        "count_greater_than_or_equal": {
          "type": "integer",
          "description": "Minimum count (inclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')."
        },
        "count_less_than": {
          "type": "integer",
          "description": "Maximum count (exclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')."
        },
        "count_less_than_or_equal": {
          "type": "integer",
          "description": "Maximum count (inclusive). Only applicable for engagement types ('opens', 'clicks', 'sent', 'delivered')."
        },
        "after": {
          "type": "string",
          "format": "date",
          "description": "Start date (YYYY-MM-DD). For 'subscribed' type, filters by subscriber_created_at. For engagement types, filters by event date. Not applicable for 'tags', 'subscriber_state', or 'attribution' types."
        },
        "before": {
          "type": "string",
          "format": "date",
          "description": "End date (YYYY-MM-DD). For 'subscribed' type, filters by subscriber_created_at. For engagement types, filters by event date. Not applicable for 'tags', 'subscriber_state', or 'attribution' types."
        },
        "states": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "active",
              "inactive",
              "bounced",
              "cancelled",
              "complained"
            ]
          },
          "description": "Subscriber lifecycle states. Required for 'subscriber_state' type; ignored for other types. Subscribers matching any of the listed states pass the filter. Strongly recommended to use `['active']` unless you specifically need other states — most subscriber-facing queries elsewhere in the app scope to active subscribers by default."
        },
        "any": {
          "type": "array",
          "description": "Array of OR conditions. Subscriber activity must match ANY of these conditions. Engagement types accept broadcasts/URLs; 'tags' accepts tag id matchers; 'attribution' accepts attribution sub-conditions (currently 'forms'). Not applicable for 'subscribed' or 'subscriber_state' types.",
          "items": {
            "oneOf": [
              {
                "title": "Broadcasts",
                "$ref": "#/$defs/BroadcastAnyCondition"
              },
              {
                "title": "URLs (clicks only)",
                "$ref": "#/$defs/UrlAnyCondition"
              },
              {
                "title": "Tag ids (tags only)",
                "$ref": "#/$defs/IdsAnyCondition"
              },
              {
                "title": "Forms (attribution only)",
                "$ref": "#/$defs/FormsAnyCondition"
              }
            ]
          }
        }
      },
      "required": [
        "type"
      ]
    },
    "FormsAnyCondition": {
      "type": "object",
      "description": "Attribution sub-condition: matches subscribers whose original signup attribution points at one of the given form / landing-page ids. Ids may refer to either a form or a legacy landing page — the attribution source does not distinguish between the two.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "forms"
          ],
          "description": "Must be 'forms'"
        },
        "ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Form / landing-page ids the subscriber's attribution should match."
        }
      },
      "required": [
        "type",
        "ids"
      ]
    },
    "IdsAnyCondition": {
      "type": "object",
      "description": "Match a list of ids. Used by the 'tags' filter to select tag ids.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "ids"
          ],
          "description": "Must be 'ids'"
        },
        "matching": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Ids the filter should match against."
        }
      },
      "required": [
        "type",
        "matching"
      ]
    },
    "UrlAnyCondition": {
      "type": "object",
      "description": "Filter by URL patterns. Only applicable for 'clicks' type. Subscriber must have clicked ANY of the specified URLs.",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "urls"
          ],
          "description": "Must be 'urls'"
        },
        "ids": {
          "type": "array",
          "items": {
            "type": "integer"
          },
          "description": "Array of URL IDs. Subscriber must have clicked ANY of these."
        },
        "urls": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Array of URL patterns. Subscriber must have clicked ANY of these."
        },
        "matching": {
          "type": "string",
          "enum": [
            "exact",
            "contains",
            "starts_with",
            "ends_with"
          ],
          "description": "URL matching strategy",
          "default": "exact"
        }
      },
      "required": [
        "type"
      ]
    }
  }
}