The Subscribers API from Kit — 7 operation(s) for subscribers.
openapi: 3.0.3
info:
title: Kit Accounts Subscribers API
version: '4.0'
servers:
- url: https://api.kit.com
tags:
- name: Subscribers
paths:
/v4/bulk/subscribers:
post:
summary: Bulk create subscribers
description: See "[Bulk & async processing](#bulk-amp-async-processing)" for more information.
tags:
- Subscribers
security:
- OAuth2: []
parameters: []
responses:
'200':
description: Creates or updates the subscribers synchronously when 100 or less subscribers are requested
content:
application/json:
schema:
type: object
properties:
subscribers:
type: array
items:
type: object
properties:
id:
type: integer
first_name:
type: string
nullable: true
email_address:
type: string
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
required:
- id
- first_name
- email_address
- state
- created_at
failures:
type: array
items:
type: object
properties:
subscriber:
type: object
properties:
first_name:
type: string
email_address:
type: string
nullable: true
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
nullable: true
required:
- first_name
- email_address
- state
- created_at
errors:
type: array
items:
type: string
required:
- subscriber
- errors
required:
- subscribers
- failures
example:
subscribers:
- id: 596
first_name: null
email_address: brooke@convertkit.dev
state: active
created_at: '2023-02-17T11:43:55Z'
- id: 597
first_name: Camille
email_address: camille@convertkit.dev
state: active
created_at: '2023-02-17T11:43:55Z'
- id: 595
first_name: Alice
email_address: alice@convertkit.dev
state: active
created_at: '2023-02-17T11:43:55Z'
failures:
- subscriber:
first_name: Benito
email_address: null
state: active
created_at: null
errors:
- Email address is invalid
'202':
description: Creates or updates subscribers asynchronously when more than 100 subscribers are requested
content:
application/json:
schema:
type: object
properties: {}
example: {}
'401':
description: Returns a 401 if the token and/or account cannot be authenticated
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- The access token is invalid
'403':
description: Returns a 403 when the number of subscribers in the request would exceed the account's subscriber limit
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- This request would exceed your subscriber limit
'413':
description: Returns a 413 when the size of the request would exceed the account's data limit for enqueued bulk requests
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- This request exceeds your queued bulk requests limit. Please wait while we process your existing requests and try again later.
'422':
description: Returns a 422 when `subscribers` is empty or not an array
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- No subscribers included for processing
requestBody:
content:
application/json:
schema:
type: object
properties:
subscribers:
type: array
items:
type: object
properties:
first_name:
type: string
nullable: true
email_address:
type: string
nullable: true
state:
type: string
nullable: true
enum:
- active
- cancelled
- bounced
- complained
- inactive
callback_url:
type: string
nullable: true
required:
- subscribers
example:
subscribers:
- first_name: Test Subscriber 0
email_address: subscriber_0@convertkit.dev
- first_name: Test Subscriber 1
email_address: subscriber_1@convertkit.dev
- first_name: Test Subscriber 2
email_address: subscriber_2@convertkit.dev
- first_name: Test Subscriber 3
email_address: subscriber_3@convertkit.dev
callback_url: null
/v4/subscribers:
get:
summary: List subscribers
tags:
- Subscribers
security:
- API Key: []
- OAuth2: []
parameters:
- name: after
description: To fetch next page of results, use `?after=<end_cursor>`
in: query
required: false
schema:
type: string
nullable: true
- name: before
description: To fetch previous page of results, use `?before=<start_cursor>`
in: query
required: false
schema:
type: string
nullable: true
- name: created_after
description: Filter subscribers who have been created after this date (format yyyy-mm-dd)
in: query
required: false
schema:
type: string
example: '2023-01-17T11:43:55Z'
- name: created_before
description: Filter subscribers who have been created before this date (format yyyy-mm-dd)
in: query
required: false
schema:
type: string
example: '2023-02-18T11:43:55Z'
- name: email_address
in: query
required: false
schema:
type: string
example: subscriber89@kit.dev,subscriber90@kit.dev,subscriber91@kit.dev
- name: include
in: query
required: false
schema:
type: string
example: attribution,tags,location
description: 'Comma-separated list of additional fields to include on each subscriber. Valid options: `attribution`, `tags`, `location`, `canceled_at`. `canceled_at` may only be used together with `status=cancelled`.'
- name: include_total_count
description: Set to `true` to include the `total_count` in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.
in: query
required: false
schema:
type: boolean
example: false
- name: per_page
description: Number of results per page. Default 500, maximum 1000.
in: query
required: false
schema:
type: number
nullable: true
example: 10
- name: slim
in: query
required: false
schema:
type: boolean
example: false
description: When `true`, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed.
- name: sort_field
in: query
required: false
schema:
type: string
example: cancelled_at
- name: sort_order
in: query
required: false
schema:
type: string
enum:
- asc
- desc
example: asc
- name: status
description: Filter subscribers who have this status (`active`, `inactive`, `bounced`, `complained`, `cancelled` or `all`). Defaults to `active`.
in: query
required: false
schema:
type: string
enum:
- active
- inactive
- bounced
- complained
- cancelled
- all
example: bounced
- name: updated_after
description: Filter subscribers who have been updated after this date (format yyyy-mm-dd)
in: query
required: false
schema:
type: string
example: '2023-01-17T11:43:55Z'
- name: updated_before
description: Filter subscribers who have been updated before this date (format yyyy-mm-dd)
in: query
required: false
schema:
type: string
example: '2023-02-18T11:43:55Z'
responses:
'200':
description: Returns subscriber attribution, tags, and primary location when requested via the include param
content:
application/json:
schema:
type: object
properties:
subscribers:
type: array
items:
type: object
properties:
id:
type: integer
first_name:
type: string
nullable: true
email_address:
type: string
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
fields:
type: object
properties:
category:
type: string
nullable: true
attribution:
type: object
description: Returned when `include` contains `attribution`.
nullable: true
properties:
referrer:
type: string
nullable: true
utm_source:
type: string
nullable: true
utm_medium:
type: string
nullable: true
utm_campaign:
type: string
nullable: true
utm_term:
type: string
nullable: true
utm_content:
type: string
nullable: true
source_type:
type: string
nullable: true
source_name:
type: string
nullable: true
source_mechanism:
type: string
nullable: true
source_mechanism_id:
type: integer
nullable: true
required:
- referrer
- utm_source
- utm_medium
- utm_campaign
- utm_term
- utm_content
- source_type
- source_name
- source_mechanism
- source_mechanism_id
tags:
type: array
description: Returned when `include` contains `tags`.
items:
type: object
properties:
id:
type: integer
nullable: true
name:
type: string
nullable: true
location:
type: object
description: Returned when `include` contains `location`.
nullable: true
properties:
city:
type: string
nullable: true
state:
type: string
nullable: true
country:
type: string
nullable: true
latitude:
type: number
nullable: true
format: float
longitude:
type: number
nullable: true
format: float
timezone:
type: string
nullable: true
required:
- city
- state
- country
- latitude
- longitude
- timezone
canceled_at:
type: string
format: date-time
nullable: true
description: Returned when `include` contains `canceled_at`. Requires `status=cancelled`.
required:
- id
- state
- first_name
- email_address
- created_at
- fields
pagination:
type: object
properties:
has_previous_page:
type: boolean
has_next_page:
type: boolean
start_cursor:
type: string
end_cursor:
type: string
per_page:
type: integer
required:
- has_previous_page
- has_next_page
- start_cursor
- end_cursor
- per_page
required:
- subscribers
- pagination
example:
subscribers:
- id: 200
state: active
first_name: Alice
email_address: alice@convertkit.dev
created_at: '2023-01-27T11:43:55Z'
fields:
category: One
attribution:
referrer: https://t.co/abc123
utm_source: twitter
utm_medium: cpc
utm_campaign: spring_launch
utm_term: newsletter+for+creators
utm_content: hero_cta
source_type: form_subscription
source_name: Welcome Form
source_mechanism: landing_page
source_mechanism_id: null
tags:
- id: 1
name: VIP
location:
city: Portland
state: OR
country: US
latitude: 45.5
longitude: -122.6
timezone: America/Los_Angeles
- id: 201
state: active
first_name: Benito
email_address: benito@convertkit.dev
created_at: '2023-02-03T11:43:55Z'
fields: {}
attribution:
referrer: https://creator.kit.com/jane-smith
utm_source: kit
utm_medium: referral
utm_campaign: null
utm_term: null
utm_content: null
source_type: form_subscription
source_name: Jane Smith's Recommendations
source_mechanism: recommendations
source_mechanism_id: null
tags:
- id: 2
name: Newsletter
location:
city: Austin
state: TX
country: US
latitude: 30.27
longitude: -97.74
timezone: America/Chicago
- id: 202
state: active
first_name: Camille
email_address: camille@convertkit.dev
created_at: '2023-02-10T11:43:55Z'
fields: {}
attribution:
referrer: null
utm_source: null
utm_medium: null
utm_campaign: null
utm_term: null
utm_content: null
source_type: api_subscription
source_name: Partner Integration
source_mechanism: api
source_mechanism_id: 12345
tags: []
location: null
- id: 203
state: active
first_name: Elliot
email_address: elliot@convertkit.dev
created_at: '2023-02-13T11:43:55Z'
fields: {}
attribution:
referrer: null
utm_source: null
utm_medium: null
utm_campaign: null
utm_term: null
utm_content: null
source_type: null
source_name: null
source_mechanism: null
source_mechanism_id: null
tags:
- id: 3
name: Imported
location:
city: null
state: null
country: null
latitude: null
longitude: null
timezone: null
pagination:
has_previous_page: false
has_next_page: false
start_cursor: MjAyMy0wMS0yNyAxMTo0Mzo1NSBVVEM=
end_cursor: MjAyMy0wMi0xMyAxMTo0Mzo1NSBVVEM=
per_page: 500
'401':
description: Returns a 401 if the token and/or account cannot be authenticated
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- The access token is invalid
'422':
description: raises an error when sorting on cancelled_at without the cancelled status
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- The status param must be `cancelled` if sort_field is `cancelled_at`
x-mcp:
enabled: true
post:
summary: Create a subscriber
description: Behaves as an upsert. If a subscriber with the provided email address does not exist, it creates one with the specified first name and state. If a subscriber with the provided email address already exists, it updates the first name.<br/><br/>If you include a custom field key that does not exist on your account, the request returns an error. Use [List custom fields](/api-reference/custom-fields/list-custom-fields) to retrieve existing keys, or [Create a custom field](/api-reference/custom-fields/create-a-custom-field) to add new fields before setting them for subscribers.<br/><br/><strong>NOTE:</strong> Updating the subscriber state with this endpoint is not supported at this time.<br/><strong>NOTE:</strong> We support creating/updating a maximum of 140 custom fields at a time.
tags:
- Subscribers
security:
- API Key: []
- OAuth2: []
parameters: []
responses:
'200':
description: Returns a 200 and updates the subscriber first name when a subscriber with provided email already exists
content:
application/json:
schema:
type: object
properties:
subscriber:
type: object
properties:
id:
type: integer
first_name:
type: string
nullable: true
email_address:
type: string
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
fields:
type: object
properties: {}
required:
- id
- first_name
- email_address
- state
- created_at
- fields
required:
- subscriber
example:
subscriber:
id: 353
first_name: Alice
email_address: alice@convertkit.dev
state: inactive
created_at: '2023-02-17T11:43:55Z'
fields: {}
'201':
description: Creates a new subscriber
content:
application/json:
schema:
type: object
properties:
subscriber:
type: object
properties:
id:
type: integer
first_name:
type: string
nullable: true
email_address:
type: string
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
fields:
type: object
additionalProperties:
type: string
description: Custom field values for the subscriber, keyed by the custom field's `key`.
required:
- id
- first_name
- email_address
- state
- created_at
- fields
warnings:
type: array
items:
type: string
description: Present only when the request referenced custom field keys that don't exist on the account. Each entry names an unknown key that was ignored; the subscriber is still created or updated.
required:
- subscriber
example:
subscriber:
id: 349
first_name: Alice
email_address: alice@convertkit.dev
state: active
created_at: '2023-02-17T11:43:55Z'
fields:
birthday: Feb 17
last_name: Lamarr
source: landing page
'202':
description: Returns a 202 and asynchronously adds custom fields for the new subscriber when more than 10 custom fields are included in the request
content:
application/json:
schema:
type: object
properties:
subscriber:
type: object
properties:
id:
type: integer
first_name:
type: string
nullable: true
email_address:
type: string
state:
type: string
enum:
- active
- cancelled
- bounced
- complained
- inactive
created_at:
type: string
fields:
type: object
properties:
company:
nullable: true
coupon:
nullable: true
enrolled_in_coaching:
nullable: true
how_did_you_hear_about_us:
nullable: true
interests:
nullable: true
lead_score:
nullable: true
phone_number:
nullable: true
postal_code:
nullable: true
role:
nullable: true
social_media:
nullable: true
website:
nullable: true
required:
- company
- coupon
- enrolled_in_coaching
- how_did_you_hear_about_us
- interests
- lead_score
- phone_number
- postal_code
- role
- social_media
- website
required:
- id
- first_name
- email_address
- state
- created_at
- fields
required:
- subscriber
example:
subscriber:
id: 351
first_name: Alice
email_address: alice@convertkit.dev
state: active
created_at: '2023-02-17T11:43:55Z'
fields:
company: null
coupon: null
enrolled_in_coaching: null
how_did_you_hear_about_us: null
interests: null
lead_score: null
phone_number: null
postal_code: null
role: null
social_media: null
website: null
'401':
description: Returns a 401 if the token and/or account cannot be authenticated
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- The access token is invalid
'422':
description: Returns a 422 with an error message when one or more of the parameters are invalid
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
example:
errors:
- Email address is invalid
requestBody:
content:
application/json:
schema:
type: object
properties:
first_name:
type: string
nullable: true
email_address:
# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/convertkit/refs/heads/main/openapi/convertkit-subscribers-api-openapi.yml