Getting started
Overview
Calls for ConvertKit API v3 are relative to the URL https://api.convertkit.com/v3/
API v3 is no longer in active development, with V4 now available via a closed beta. Documentation for this can be found here.
V4 offers a ground-up rebuild of our developer tooling, vastly improving performance while adding a host of new and quality of life features - all created using industry standard patterns and design - including seamless OAuth authentication for creators, bulk endpoints and a fully functional broadcast API, allowing full HTML support and targeting.
It will also be the sole access point for deeper integrations and plugins opening up a way for you to create native tools to supercharge how your users work.
Planning your integration
Sweet! You’re building an integration with ConvertKit. We’re thrilled that you want to help expand our ever-growing platform! Our API offers a host of functionality to help our creators automate a bunch of tasks to help make their lives as easy as possible, especially by helping link their tech marketing stack together in perfect harmony.
As long as the authenticated account’s plan is eligible for use with the API and integrations, you will be able to create and send broadcasts to your subscribers, manage your email list through tags and custom fields, import in purchase data from your favourite e-commerce platforms and much, much more.
If you are a third party developer, once your integration is complete, why not reach out to us here to be included on our integrations page as well?
API Basics
API key
All API calls require the api_key
parameter. You can find your API Key in the ConvertKit Account page.
API secret key
Some API calls require the api_secret
parameter. All calls that require api_key
also work with api_secret
, there's no need to use both. This key grants access to sensitive data and actions on your subscribers. You should treat it as your password and do not use it in any client-side code (usually that means JavaScript).
Integration Key
As mentioned above, if you are working on a larger integration, we strongly advise the use of an integration_key
, which when received gives us the ability to differentiate API calls from your application from other requesters. This will ensure that our team will be able to monitor, triage and troubleshoot any potential issues we see with the integration and offer support to ensure everything works as expected. In order to access this functionality, please request an integration_key
via the form found in the Building a larger integration? section above, and include the following as an optional parameter in all of your calls to the API - "integration_key":"<YOUR INTEGRATION KEY HERE>”.
Responses
When an API call succeeds, the API will return a 200 or 201 HTTP response and a JSON response body unless otherwise noted.
If there's some error, the API will return an HTTP response in the 400 or 500 range and a response body indicating what the error was. For example:
{ "error": "Authorization Failed", "message": "API Key not present" }
with a 401 error.
Bad data
When you create or update a field, you may receive an HTTP 422 if any fields contain bad data or required fields are missing.
Rate limiting
Our rate limit is no more than 120 requests over a rolling 60 second period, for a given api key.
If your request rate exceeds our limits, you will receive a 429 response, which your code should gracefully handle. We recommend spacing out your requests and performing an exponential backoff to keep within the limit.
Internal server errors
If the server is overloaded or you encounter a bug, you will get a 500 error. Try again after a short period, and if you continue to encounter an error, please raise the issue with support.
Account
Show the current account
Example request
curl https://api.convertkit.com/v3/account?api_secret=<your_secret_api_key>
Example response
{
"name":"Acme Corp.",
"primary_email_address":"you@example.com"
}
Endpoint
GET /v3/account
Required parameters
-
api_secret
- Your API secret key
Forms
List forms
Example request
curl https://api.convertkit.com/v3/forms?api_key=<your_public_api_key>
Example response
{
"forms": [
{
"id": 1,
"name": "A Form",
"created_at": "2016-02-28T08:07:00Z",
"type": "embed",
"url": "https://app.convertkit.com/landing_pages/1",
"embed_js": "http://api.convertkit.dev/v3/forms/1.js?api_key=<your_public_api_key>",
"embed_url": "http://api.convertkit.dev/v3/forms/1.html?api_key=<your_public_api_key>",
"title": "Join the newsletter",
"description": "Form description text.",
"sign_up_button_text": "Subscribe",
"success_message": "Success! Now check your email to confirm your subscription."
},
{
"id": 2,
"name": "A Landing Page",
"created_at": "2016-02-28T08:07:00Z",
"type": "hosted",
"url": "https://app.convertkit.com/r4ndom_url/TWWDNTHT",
"embed_js": "http://api.convertkit.dev/v3/forms/2.js?api_key=<your_public_api_key>",
"embed_url": "http://api.convertkit.dev/v3/forms/2.html?api_key=<your_public_api_key>",
"title": "Join the newsletter",
"description": "<p>Landing page description text.</p>",
"sign_up_button_text": "Subscribe",
"success_message": "Success! Now check your email to confirm your subscription."
}
]
}
Get a list of all the forms for your account.
Endpoint
GET /v3/forms
Required parameters
-
api_key
- Your account API key
Add subscriber to a form
Example request
curl -X POST https://api.convertkit.com/v3/forms/<form_id>/subscribe\
-H "Content-Type: application/json; charset=utf-8"\
-d '{ \
"api_key": "<your_public_api_key>",\
"email": "jonsnow@example.com"\
}'
# Include a tag during subscribing
curl -X POST https://api.convertkit.com/v3/forms/<form_id>/subscribe\
-H "Content-Type: application/json; charset=utf-8"\
-d '{ \
"api_key": "<your_public_api_key>",\
"email": "jonsnow@example.com",\
"tags": [1234, 5678]\
}'
Example response
{
"subscription": {
"id": 1,
"state": "inactive",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "form",
"subscriber": {
"id": 1
}
}
}
Subscribe an email address to one of your forms.
Endpoint
POST /v3/forms/#{form_id}/subscribe
Required parameters
-
api_key
- Your account API key -
email
- Subscriber email address
Optional parameters
-
first_name
- Subscriber first name -
fields
- Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here. -
tags
- Array of tag ids to subscribe to
Deprecated parameters
-
courses
- Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly. -
forms
- Array of form ids to subscribe to. You should add the subscriber to each form individually. -
name
- Subscriber first name. You should prefer usingfirst_name
listed above.
List subscriptions to a form
Example Request
curl https://api.convertkit.com/v3/forms/<form_id>/subscriptions?api_secret=<your_secret_api_key>
Example response
{
"total_subscriptions": 2,
"page": 1,
"total_pages": 1,
"subscriptions": [
{
"id": 1,
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "form",
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
},
},
{
"id": 2,
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "form",
"subscriber": {
"id": 2,
"first_name": "Arya",
"email_address": "arya@example.com",
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"fields": {
"last_name": "Stark"
}
},
}
]
}
List subscriptions to a form including subscriber data.
Endpoint
GET /v3/forms/#{form_id}/subscriptions
Required parameters
-
api_secret
- Your API secret key
Optional parameters
-
sort_order
-asc
ordesc
:asc
to list subscribers added oldest to newest,desc
to list subscribers added newest to oldest.asc
is the default order. -
subscriber_state
-active
orcancelled
: receive only active subscribers or cancelled subscribers -
page
- The page of results being requested. Default value is1
. Each page of results will contain up to 50 forms.
Sequences
NOTE: Sequences were formerly referred to as Courses API v3 retains the previous naming conventions, but will accept requests to sequences
as the endpoint as well.
List sequences
Example request
curl https://api.convertkit.com/v3/sequences?api_key=<your_public_api_key>
Example response
{
"courses": [
{
"id": 1,
"name": "My First Sequence",
"created_at": "2016-02-28T08:07:00Z"
},
{
"id": 2,
"name": "My Second Sequence",
"created_at": "2016-02-28T08:07:00Z"
}
]
}
Returns a list of sequences for the account.
Endpoint
GET /v3/sequences
Required parameters
-
api_key
- Your account API key
Add subscriber to a sequence
Example request
curl -X POST https://api.convertkit.com/v3/sequences/<sequence_id>/subscribe\
-H "Content-Type: application/json; charset=utf-8"\
-d '{ \
"api_key": "<your_public_api_key>",\
"email": "jonsnow@example.com"\
}'
Example response
{
"subscription": {
"id": 2,
"state": "inactive",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "course",
"subscriber": {
"id": 1
}
}
}
Subscribe an email address to one of your sequences.
Endpoint
POST /v3/sequences/#{sequence_id}/subscribe
Required parameters
-
api_key
- Your account API key -
email
- Subscriber email address
Optional parameters
-
first_name
- Subscriber first name -
fields
- Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here. -
tags
- Array of tag ids to subscribe to.
Deprecated parameters
-
courses
- Array of sequence ids to subscribe to. You should add the subscriber to each course individually. -
forms
- Array of form ids to subscribe to. You should add the subscriber to the form directly. -
name
- Subscriber first name. You should prefer usingfirst_name
listed above.
List subscriptions to a sequence
Example request
curl https://api.convertkit.com/v3/sequences/<sequence_id>/subscriptions?api_secret=<your_secret_api_key>
Example response
{
"total_subscriptions": 2,
"page": 1,
"total_pages": 1,
"subscriptions": [
{
"id": 1,
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "course",
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
},
},
{
"id": 2,
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "course",
"subscriber": {
"id": 2,
"first_name": "Arya",
"email_address": "arya@example.com",
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"fields": {
"last_name": "Stark"
}
},
}
]
}
List subscriptions to a sequence including subscriber data.
Endpoint
GET /v3/sequences/#{sequence_id}/subscriptions
Required parameters
-
api_secret
- your API secret key
Optional parameters
-
sort_order
-asc
ordesc
:asc
to list subscribers added oldest to newest,desc
to list subscribers added newest to oldest.asc
is the default order. -
subscriber_state
-active
orcancelled
: receive only active subscribers or cancelled subscribers -
page
- The page of results being requested. Default value is1
. Each page of results will contain up to 50 sequences.
Tags
List tags
Example request
curl https://api.convertkit.com/v3/tags?api_key=<your_public_api_key>
Example response
{
"tags": [
{
"id": 1,
"name": "House Stark",
"created_at": "2016-02-28T08:07:00Z"
},
{
"id": 2,
"name": "House Lannister",
"created_at": "2016-02-28T08:07:00Z"
}
]
}
Returns a list of tags for the account.
Endpoint
GET /v3/tags
Required parameters
-
api_key
- Your account API key
Create a tag
Example request
Single tag
curl -X POST https://api.convertkit.com/v3/tags\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",\
"tag": {\
"name": "Example Tag"\
} }'
Multiple tags
curl -X POST https://api.convertkit.com/v3/tags
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",\
"tag": [{\
"name": "Example Tag"\
}, {\
"name": "Example Tag 2"\
}] }'
Example response
{
"account_id": 1,
"created_at": "2017-04-12T11:10:32Z",
"deleted_at": null,
"id": 1,
"name": "Example Tag",
"state": "available",
"updated_at": "2017-04-12T11:10:32Z"
}
A request to create multiple tags will return a JSON array with the same type of objects:
[{
"account_id": 1,
"created_at": "2017-04-12T11:10:32Z",
"deleted_at": null,
"id": 1,
"name": "Example Tag",
"state": "available",
"updated_at": "2017-04-12T11:10:32Z"
},
{
"account_id": 1,
"created_at": "2017-04-12T11:11:566Z",
"deleted_at": null,
"id": 1,
"name": "Example Tag 2",
"state": "available",
"updated_at": "2017-04-12T11:11:566Z"
}]
Endpoint
POST /v3/tags
Required parameters
-
api_key
- Your API secret key -
tag
- a JSON object or an array of JSON objects, respectively, that includes the tag name-
{ "name": "Example Tag" }
-
Tag a subscriber
Example request
curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/subscribe\
-H "Content-Type: application/json; charset=utf-8"\
-d '{ \
"api_secret": "<your_secret_api_key>",\
"email": "jonsnow@example.com"\
}'
Example response
{
"subscription": {
"id": 3,
"state": "inactive",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "tag",
"subscriber": {
"id": 1
}
}
}
Tags are handled as subscriptions. Subscribe an email address to a tag to have that tag applied to the subscriber with that email address.
Endpoint
POST /v3/tags/#{tag_id}/subscribe
Required parameters
-
api_secret
- Your API secret key -
email
- Subscriber email address
Optional parameters
-
first_name
- Subscriber first name -
fields
- Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here. -
tags
- Array of tag ids to subscribe to
Deprecated parameters
-
courses
- Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly. -
forms
- Array of form ids to subscribe to. You should add the subscriber to the form directly. -
name
- Subscriber first name. You should prefer usingfirst_name
listed above.
Remove tag from a subscriber
Example request
curl -X DELETE https://api.convertkit.com/v3/subscribers/<subscriber_id>/tags/<tag_id>?api_secret=<your_secret_api_key>
Example response
{
"id": 1,
"name": "House Stark",
"created_at": "2016-02-28T08:07:00Z"
}
Endpoint
DELETE /v3/subscribers/#{subscriber_id}/tags/#{tag_id}
Required parameters
-
api_secret
- Your API secret key
Remove tag from a subscriber by email
Example request
curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/unsubscribe\
-H "Content-Type: application/json; charset=utf-8"\
-d '{ \
"api_secret": "<your_secret_api_key>",\
"email": "jonsnow@example.com"\
}'
Example response
{
"id": 1,
"name": "House Stark",
"created_at": "2016-02-28T08:07:00Z"
}
Endpoint
POST /v3/tags/#{tag_id}/unsubscribe
Required parameters
-
api_secret
- Your API secret key -
email
- Subscriber email address
List subscriptions to a tag
Example request
curl https://api.convertkit.com/v3/tags/<tag_id>/subscriptions?api_secret=<your_secret_api_key>
Example response
{
"total_subscriptions": 2,
"page": 1,
"total_pages": 1,
"subscriptions": [
{
"id": 1,
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "tag",
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
},
},
{
"id": 2,
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"source": null,
"referrer": null,
"subscribable_id": 1,
"subscribable_type": "tag",
"subscriber": {
"id": 2,
"first_name": "Arya",
"email_address": "arya@example.com",
"state": "active",
"created_at": "2016-02-27T08:07:00Z",
"fields": {
"last_name": "Stark"
}
},
}
]
}
List subscriptions to a tag including subscriber data.
Endpoint
GET /v3/tags/#{tag_id}/subscriptions
Required parameters
-
api_secret
- Your API secret key
Optional parameters
-
sort_order
-asc
ordesc
:asc
to list subscribers added oldest to newest,desc
to list subscribers added newest to oldest.asc
is the default order. -
subscriber_state
-active
orcancelled
: receive only active subscribers or cancelled subscribers -
page
- The page of results being requested. Default value is1
. Each page of results will contain up to 50 tags.
Subscribers
List subscribers
Example request
curl https://api.convertkit.com/v3/subscribers?api_secret=<your_secret_api_key>&from=2016-02-01&to=2015-02-28
Example response
{
"total_subscribers": 3,
"page": 1,
"total_pages": 1,
"subscribers": [
{
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
},
{
"id": 2,
"first_name": "Arya",
"email_address": "aryastark@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Stark"
}
}
]
}
Returns a list of your subscribers. For unsubscribes only, use the cancelled_at
value for sort_field
param (currently the only supported extra sort field). Search subscribers by email address by providing the email_address
param.
Endpoint
GET /v3/subscribers
Required parameters
-
api_secret
- Your API secret key
Optional parameters
-
page
- The page of results being requested. Default value is1
. Each page of results will contain up to 50 subscribers. -
from
- Filter subscribers added on or after this date (format yyyy-mm-dd) -
to
- Filter subscribers added on or before this date (format yyyy-mm-dd) -
updated_from
- Filter subscribers who have been updated after this date (format yyyy-mm-dd) -
updated_to
- Filter subscribers who have been updated before this date (format yyyy-mm-dd) -
sort_order
- Sort order for results (asc
ordesc
) -
sort_field
- Field to sort by (cancelled_at
) -
email_address
- Search subscribers by email address
View a single subscriber
Example request
curl https://api.convertkit.com/v3/subscribers/<subscriber_id>?api_secret=<your_secret_api_key>
Example response
{
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
}
}
Returns data for a single subscriber
Endpoint
GET /v3/subscribers/#{subscriber_id}
Required parameters
-
api_secret
- Your API secret key
Update subscriber
Example request
curl -X PUT https://api.convertkit.com/v3/subscribers/<subscriber_id>\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",\
"first_name": "Jon",\
"email_address": "jonsnow@example.com",\
"fields": {\
"last_name": "Snow"\
} }'
Example response: Up to 10 custom fields, status
200
{
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
}
}
Example response: 11 to 140 custom fields, status
202
{
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
}
}
Updates the information for a single subscriber.
Endpoint
PUT /v3/subscribers/#{subscriber_id}
Required parameters
-
api_secret
- Your API secret key
Optional parameters
-
first_name
- Updated first name for the subscriber. -
email_address
- Updated email address for the subscriber. -
fields
- Updated custom field(s) for your subscriber as object of key/value pairs. The custom field(s) must exist before you can use it here.
NOTE: The API response returned when updating custom fields is dependent on the number of custom fields in the request, as shown by the examples at right. A maximum of 140 custom fields are allowed. Requests that exceed this limit will return a response of 400
.
Unsubscribe subscriber
Example request
curl -x PUT https://api.convertkit.com/v3/unsubscribe\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",\
"email": "jonsnow@example.com" }'
Example response
{
"subscriber": {
"id": 1,
"first_name": "Jon",
"email_address": "jonsnow@example.com",
"state": "active",
"created_at": "2016-02-28T08:07:00Z",
"fields": {
"last_name": "Snow"
}
}
}
Unsubscribe an email address from all your forms and sequences.
Endpoint
PUT /v3/unsubscribe
Required parameters
-
api_secret
- Your API secret key -
email
- Subscriber email address
List tags for a subscriber
Example request
curl https://api.convertkit.com/v3/subscribers/<subscriber_id>/tags?api_key=<your_public_api_key>
Example response
{
"tags": [
{
"id": 1,
"name": "Email Newsletter",
"created_at": "2016-06-09T17:54:22Z"
}
]
}
Lists all the tags for a subscriber.
Endpoint
GET /v3/subscribers/#{subscriber_id}/tags
Required parameters
-
api_key
- Your account API key
Broadcasts
NOTE: We are actively working on new API features to further support these endpoints. If there are any improvements or feedback you have, please share your thoughts via this form.
A broadcast is a one-time email blast that can either be sent right away or scheduled for a future time and date.
List broadcasts
Example request
curl https://api.convertkit.com/v3/broadcasts?page=1&api_secret=<your_secret_api_key>
Example response
{
"broadcasts": [
{
"id": 1,
"created_at": "2014-02-13T21:45:16.000Z",
"subject": "Welcome to my Newsletter!"
},
{
"id": 2,
"created_at": "2014-02-20T11:40:11.000Z",
"subject": "Check out my latest blog posts!"
},
{
"id": 3,
"created_at": "2014-02-29T08:21:18.000Z",
"subject": "How to get my free masterclass"
}
]
}
Returns a list of the broadcasts for your account.
Endpoint
GET /v3/broadcasts
Required parameters
-
api_secret
- Your API secret key
Optional parameters
-
page
- The page of results being requested. Default value is1
. Each page of results will contain up to 50 broadcasts. -
sort_order
- Sort order for results (asc
ordesc
). The default isasc
with the oldest first.
Create a broadcast
Note: See the top of this section for additional information and to provide feedback.
Example request
curl -X POST https://api.convertkit.com/v3/broadcasts\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",
"description": "Paid member newsletter for 04/26",
"subject": "Weekly Update (04/26)",
"content": "<p>Your content here</p>" }'
Example response
{
"broadcast": {
"id": 1,
"created_at": "2020-02-14T00:00:00.000Z",
"subject": "Weekly Update (04/26)",
"description": "Paid member newsletter for 04/26",
"content": "<p>Your content here</p>",
"public": false,
"published_at": null,
"send_at": null,
"thumbnail_alt": null,
"thumbnail_url": null,
"email_address": "default@example.com",
"email_layout_template": "Text Only"
}
}
Create a draft or scheduled broadcast. You can create a draft broadcast without any attributes. Scheduled broadcasts at a minimum should contain a subject line and your content. Unless otherwise specified, new broadcasts will be sent from your account's default email address and with your account's default email template.
Endpoint
POST /v3/broadcasts
Required parameters
api_secret
- Your API secret key
Optional parameters
content
- The broadcast's email content - this can contain text and simple HTML markdown (such ash1
,img
orp
tags)description
- An internal description of this broadcastemail_address
- Sending email address; leave blank to use your account's default sending email addressemail_layout_template
- Name of the email template to use; leave blank to use your account's default email templatepublic
- Specifies whether or not this is a public postpublished_at
- Specifies the time that this post was published (applicable only to public posts)send_at
- Time that this broadcast should be sent; leave blank to create a draft broadcast. If set to a future time, this is the time that the broadcast will be scheduled to send.subject
- The broadcast email's subjectthumbnail_alt
- Specify the ALT attribute of the public thumbnail image (applicable only to public posts)thumbnail_url
- Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)
Retrieve a specific broadcast
Note: This endpoint is newly released. See the top of this section for additional information and to provide feedback.
Example request
curl https://api.convertkit.com/v3/broadcasts/<broadcast_id>?api_secret=<your_secret_api_key>
Example response
{
"broadcast": {
"id": 1,
"created_at": "2020-02-14T00:00:00.000Z",
"subject": "Weekly Update (04/26)",
"description": "Paid member newsletter for 04/26",
"content": "<p>Your content here</p>",
"public": false,
"published_at": null,
"send_at": null,
"thumbnail_alt": null,
"thumbnail_url": null,
"email_address": "default@example.com",
"email_layout_template": "Text Only"
}
}
Retrieve the details of a specific broadcast, including draft, scheduled, and previously-sent broadcasts.
Endpoint
GET /v3/broadcasts/#{broadcast_id}
Required parameters
api_secret
- Your API secret keybroadcast_id
- The ID of the broadcast you want to retrieve
Get stats
Example request
curl https://api.convertkit.com/v3/broadcasts/<broadcast_id>/stats?api_secret=<your_secret_api_key>
Example response
{
"broadcast": [
{
"id":1,
"stats":
{
"recipients": 82,
"open_rate": 60.97560975609756,
"click_rate": 23.170731707317074,
"unsubscribes": 9,
"total_clicks": 15,
"show_total_clicks": false,
"status": "completed",
"progress": 100.0
}
}
]
}
Get the statistics (recipient count, open rate, click rate, unsubscribe count, total clicks, status, and send progress) for a specific broadcast.
Endpoint
GET /v3/broadcasts/#{broadcast_id}/stats
Required parameters
-
api_secret
- Your API secret key -
broadcast_id
- The ID of the broadcast you want to retrieve
Update a broadcast
Note: This endpoint is newly released. See the top of this section for additional information and to provide feedback.
Example request
curl -X PUT https://api.convertkit.com/v3/broadcasts/1\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",
"content": "<h1>Welcome to our first newsletter!</h1><p>...</p>",
"email_address": "custom@example.com",
"email_layout_template": "My Branded Template",
"send_at": "2020-02-16T00:14:00.000Z" }'
Example response
{
"broadcast": {
"id": 1,
"created_at": "2020-02-14T00:00:00.000Z",
"subject": "Weekly Update (04/26)",
"description": "Paid member newsletter for 04/26",
"content": "<h1>Welcome to our first newsletter!</h1><p>...</p>",
"public": false,
"published_at": null,
"send_at": "2020-02-16T00:14:00.000Z",
"thumbnail_alt": null,
"thumbnail_url": null,
"email_address": "custom@example.com",
"email_layout_template": "My Branded Template"
}
}
Update the attributes of a specific broadcast. Broadcasts that are currently sending or that have been sent may not be updated.
Endpoint
PUT /v3/broadcasts/#{broadcast_id}
Required parameters
api_secret
- Your API secret keybroadcast_id
- The ID of the broadcast you want to update
Optional parameters
content
- The broadcast's email HTML contentdescription
- An internal description of this broadcastemail_address
- Sending email address; leave blank to use your account's default sending email addressemail_layout_template
- Name of the email template to use; leave blank to use your account's default email templatepublic
- Specifies whether or not this is a public postpublished_at
- Specifies the time that this post was published (applicable only to public posts)send_at
- Time that this broadcast should be sent; leave blank to create a "draft" broadcast. If set to a future time, this is the time that the broadcast will be scheduled to send.subject
- The broadcast's email subjectthumbnail_alt
- Specify the ALT attribute of the public thumbnail image (applicable only to public posts)thumbnail_url
- Specify the URL of the thumbnail image to accompany the broadcast post (applicable only to public posts)
Destroy a broadcast
Note: This endpoint is newly released. See the top of this section for additional information and to provide feedback.
Example request
curl -X DELETE https://api.convertkit.com/v3/broadcasts/1\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>" }'
Example response
No content will be returned.
Permanently delete a draft or scheduled broadcast record. Broadcasts that are currently sending or that have been sent may not be deleted.
Endpoint
DELETE /v3/broadcasts/#{broadcast_id}
Required parameters
api_secret
- Your API secret keybroadcast_id
- The ID of the broadcast you want to destroy
Webhooks
Example JSON Payload for "subscriber.#{hook_name}"
{
"subscriber": {
"id": 1,
"first_name": "John",
"email_address": "John@example.com",
"state": "active",
"created_at": "2018-02-15T19:40:24.913Z",
"fields": {
"My Custom Field": "Value"
}
}
}
Example JSON Payload for "purchase.#{hook_name}"
{
"id": 8,
"transaction_id": "123-abcd-456-efgh",
"status": "paid",
"email_address": "crashoverride@hackers.com",
"currency": "JPY",
"transaction_time": "2018-03-17T11:28:04Z",
"subtotal": 20.0,
"shipping": 2.0,
"discount": 3.0,
"tax": 2.0,
"total": 21.0,
"products": [
{
"unit_price": 5.0,
"quantity": 2,
"sku": "7890-ijkl",
"name": "Floppy Disk (512k)"
},
{
"unit_price": 10.0,
"quantity": 1,
"sku": "mnop-1234",
"name": "Telephone Cord (data)"
}
]
}
Webhooks are automations that will receive subscriber data when a subscriber event is triggered, such as when a subscriber completes a sequence.
When a webhook is triggered, a POST
request will be made to your URL with a JSON payload.
Create a webhook
Example request: Create a webhook automation to receive subscriber data at
http://example.com/incoming
when a subscriber is activated.
curl -X POST https://api.convertkit.com/v3/automations/hooks\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",\
"target_url": "http://example.com/incoming",\
"event": { "name": "subscriber.subscriber_activate" } }'
Example response
{
"rule": {
"id": 1,
"account_id": 2,
"event": {
"name": "subscriber_activate"
}
}
}
Example request: Create a webhook automation to receive subscriber data at
http://example.com/incoming
when a sequence is completed.
curl -X POST https://api.convertkit.com/v3/automations/hooks
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",\
"target_url": "http://example.com/incoming",\
"event": { "name": "subscriber.course_complete", "sequence_id": 18" } }'
Example response
{
"rule": {
"id": 43,
"account_id":2,
"event": {
"name": "course_complete",
"sequence_id": 18
},
"target_url":"http://example.com/"
}
}
Create a webhook that will be called when a subscriber event occurs.
Endpoint
POST /v3/automations/hooks
Required parameters
-
api_secret
- Your API secret key -
target_url
- The URL that will receive subscriber data when the event is triggered -
event
- JSON object that includes the trigger name and extra information when needed. For example:-
{ "name": "subscriber.subscriber_activate" }
-
{ "name": "purchase.purchase_create" }
-
{ "name": "subscriber.tag_add", "tag_id": 4 }
-
These are the available event types:
-
"subscriber.subscriber_activate"
-
"subscriber.subscriber_unsubscribe"
-
"subscriber.subscriber_bounce"
-
"subscriber.subscriber_complain"
-
"subscriber.form_subscribe"
, required parameter:form_id [Integer]
-
"subscriber.course_subscribe"
, required parameter:course_id [Integer]
-
"subscriber.course_complete"
, required parameter:course_id [Integer]
-
"subscriber.link_click"
, required parameter:initiator_value [String]
as a link URL -
"subscriber.product_purchase"
, required parameter:product_id [Integer]
-
"subscriber.tag_add"
, required parameter:tag_id [Integer]
-
"subscriber.tag_remove"
, required parameter:tag_id [Integer]
-
"purchase.purchase_create"
Destroy webhook
Example request
curl -X DELETE https://api.convertkit.com/v3/automations/hooks/<rule_id>\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>" }'
Example response
{
"success": true
}
Deletes a webhook.
Endpoint
DELETE /v3/automations/hooks/#{rule_id}
Required parameters
-
api_secret
- Your API secret key
Custom Fields
A custom field allows you to collect subscriber information beyond the standard fields of first name and email address. An example would be a custom field called last name so you can get the full names of your subscribers. You create a custom field, and then you're able to use that in your forms or with the API (see the Subscribers endpoint for adding custom field values to a subscriber.)
Note that you must create a custom field before you can use it with the subscribe methods on the forms, sequences, and tags endpoints.
List fields
Example request
curl -X GET 'https://api.convertkit.com/v3/custom_fields?api_key=<your_public_api_key>'
Example response
{
"custom_fields":
[
{
"id": 1,
"name": "ck_field_1_last_name",
"key": "last_name",
"label": "Last Name"
},
{
"id": 2,
"name": "ck_field_2_occupation",
"key": "occupation",
"label": "Occupation"
},
]
}
List all of your account's custom fields.
Endpoint
GET /v3/custom_fields
Required parameters
-
api_key
- Your account API key
Create field
Example request
# Single custom field
curl -X POST https://api.convertkit.com/v3/custom_fields\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",
"label": "Occupation" }'
# Multiple custom fields
curl -X POST https://api.convertkit.com/v3/custom_fields\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",
"label": ["Occupation", "Location"] }'
Example response: single custom field
{
"id": 1,
"name": "ck_field_1_occupation",
"key": "occupation",
"label": "Occupation"
}
Example response: multiple custom fields
[{
"id": 1,
"name": "ck_field_1_occupation",
"key": "occupation",
"label": "Occupation"
},
{
"id": 2,
"name": "ck_field_2_occupation",
"key": "location",
"label": "Location"
}]
Create a custom field for your account. The label field must be unique to your account. Whitespace will be removed from the beginning and the end of your label.
Additionally, a key field and a name field will be generated for you. The key is an ASCII-only, lowercased, underscored representation of your label. This key must be unique to your account. Keys are used in personalization tags in sequences and broadcasts. Names are unique identifiers for use in the HTML of custom forms. They are made up of a combination of ID and the key of the custom field prefixed with "ck_field".
A maximum of 140 custom fields are allowed. Requests that exceed this limit will return a response of 400
.
Endpoint
POST /v3/custom_fields
Required parameters
-
api_secret
- Your API secret key -
label
- The label(s) of the custom field
Update field
Example request
curl -X PUT https://api.convertkit.com/v3/custom_fields/1\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>",
"label": "Profession" }'
Example response
No content will be returned.
Updates a custom field label (see Create field above for more information on labels). Note that the key will change but the name remains the same when the label is updated.
Warning: An update to a custom field will break all of the liquid personalization tags in emails that reference it - e.g. if you update a Zip_Code
custom field to Post_Code
, all liquid tags referencing {{ subscriber.Zip_Code }}
would no longer work and need to be replaced with {{ subscriber.Post_Code }}
.
NOTE: The API response returned when updating custom fields is dependent on the number of custom fields in the request, as shown by the examples at right. A maximum of 140 custom fields are allowed. Requests that exceed this limit will return a response of 400
.
Endpoint
PUT /v3/custom_fields/#{your custom field ID}
Required parameters
-
api_secret
- Your API secret key -
id
- The ID of your custom field -
label
- The label of the custom field
Destroy field
Example request
curl -X DELETE https://api.convertkit.com/v3/custom_fields/1\
-H 'Content-Type: application/json'\
-d '{ "api_secret": "<your_secret_api_key>" }'
Example response
No content will be returned.
Destroys a custom field. Note that this will remove all data in this field from your subscribers.
Endpoint
DELETE /v3/custom_fields/#{your custom field ID}
Required parameters
-
api_secret
- Your API secret key -
id
- The ID of your custom field
Purchases
List purchases
Example request
curl https://api.convertkit.com/v3/purchases?api_secret=<your_secret_api_key>
Example response
{
"total_purchases": 2,
"page": 1,
"total_pages": 1,
"purchases": [
{
"id": 3,
"transaction_id": "123-abcd-456-efgh",
"status": "paid",
"email_address": "x@example.com",
"currency": "JPY",
"transaction_time": "2018-03-17T11:28:04Z",
"subtotal": 20.0,
"shipping": 2.0,
"discount": 3.0,
"tax": 2.0,
"total": 21.0,
"products": [
{
"unit_price": 5.0,
"quantity": 2,
"sku": "7890-ijkl",
"name": "Floppy Disk (512k)"
},
{
"unit_price": 10.0,
"quantity": 1,
"sku":"mnop-1234",
"name":"Telephone Cord (data)"
}
]
},
{
"id": 4,
"transaction_id": "123-abcd-457-efgh",
"status": "paid",
"email_address": "x@example.com",
"currency": "USD",
"transaction_time": "2018-03-17T11:28:04Z",
"subtotal": 20.0,
"shipping": 2.0,
"discount": 3.0,
"tax": 2.0,
"total": 21.0,
"products": [
{
"unit_price": 5.0,
"quantity": 2,
"sku": "7890-ijkl",
"name": "Floppy Disk (512k)"
},
{
"unit_price": 10.0,
"quantity": 1,
"sku": "mnop-1234",
"name": "Telephone Cord (data)"
}
]
}
]
}
Failure response. For example, when
api_secret
is not provided:HTTP/1.1 401 Unauthorized
{
"error":"Authorization Failed",
"message":"You do not have sufficient permissions to access this resource"
}
Show all purchases for an account
Endpoint
GET /v3/purchases
Required parameters
-
api_secret
- Your API secret key
Optional parameters
-
page
- The page of results being requested. Default value is1
. Each page of results will contain up to 50 purchases.
Retrieve a specific purchase
Example request
curl https://api.convertkit.com/v3/purchases/<purchase_id>?api_secret=<your_secret_api_key>
Example response
{
"id": 8,
"transaction_id": "123-abcd-456-efgh",
"status": "paid",
"email_address": "crashoverride@hackers.com",
"currency": "JPY",
"transaction_time": "2018-03-17T11:28:04Z",
"subtotal": 20.0,
"shipping": 2.0,
"discount": 3.0,
"tax": 2.0,
"total": 21.0,
"products": [
{
"unit_price": 5.0,
"quantity": 2,
"sku": "7890-ijkl",
"name": "Floppy Disk (512k)"
},
{
"unit_price": 10.0,
"quantity": 1,
"sku": "mnop-1234",
"name": "Telephone Cord (data)"
}
]
}
Failure response. For example, when
api_secret
is not provided:HTTP/1.1 401 Unauthorized
{
"error":"Authorization Failed",
"message":"You do not have sufficient permissions to access this resource"
}
Show specific purchase by ID
Endpoint
GET /v3/purchases/#{purchase_id}
Required parameters
-
api_secret
- Your API secret key -
purchase_id
- A purchase ID
Create a purchase
Example request
curl -X POST https://api.convertkit.com/v3/purchases \
-H 'Content-Type: application/json' \
-d '{ "api_secret": "<your_secret_api_key>",
"purchase": {
"transaction_id": "123-abcd-456-efgh",
"email_address": "john@example.com",
"first_name": "John",
"currency": "jpy",
"transaction_time": "2018-03-17 11:28:04",
"subtotal": 20.00,
"tax": 2.00,
"shipping": 2.00,
"discount": 3.00,
"total": 21.00,
"status": "paid",
"products": [{
"pid": 9999,
"lid": 7777,
"name": "Floppy Disk (512k)",
"sku": "7890-ijkl",
"unit_price": 5.00,
"quantity": 2
}, {
"pid": 5555,
"lid": 7778,
"name": "Telephone Cord (data)",
"sku": "mnop-1234",
"unit_price": 10.00,
"quantity": 1
}]
}
}'
Example response:
{
"id": 8,
"transaction_id": "123-abcd-456-efgh",
"status": "paid",
"email_address": "crashoverride@hackers.com",
"currency": "JPY",
"transaction_time": "2018-03-17T11:28:04Z",
"subtotal": 20.0,
"discount": 3.0,
"tax": 2.0,
"shipping": 2.00,
"total": 21.0,
"products": [
{
"unit_price": 5.0,
"quantity": 2,
"sku": "7890-ijkl",
"name": "Floppy Disk (512k)"
},
{
"unit_price": 10.0,
"quantity": 1,
"sku": "mnop-1234",
"name": "Telephone Cord (data)"
}
]
}
Failure response:
HTTP/1.1 400 Bad Request
{
"error": "Your request is missing parameters",
"message": "transaction_id can't be blank, Sku can't be blank for product: Floppy Disk (512k)"
}
Endpoint
POST /v3/purchases
Required parameters
-
api_secret
- Your API secret key -
transaction_id
- A unique ID for the purchase -
email_address
- The subscriber that the purchase belongs to -
currency
- 3 letter currency code (e.g.USD
) -
products
- Array of purchased products-
unit_price
- Product price -
quantity
- Product quantity -
name
- Product name -
pid
- This is your identifier for a product. Each product provided in the 'products' array must have a unique pid. Variants of the same product should have the same pid. -
lid
- Each product should have a unique lid (i.e., line item identifier) for this purchase.
-
Required for third party integrations
Are you building an integration? Please fill out this form and we will help you get set up.
-
purchase.integration
- The name of your integration (i.e. eBay) -
integration_key
- A token for tracking integrations
Optional parameters
-
first_name
- The first name of the subscriber -
subtotal
- The subtotal of the purchase -
tax
- Tax applied to purchase -
shipping
- Shipping amount applied to purchase -
discount
- Discount amount applied to purchase -
total
- Total cost of the purchase -
transaction_time
- date and time of purchase as ISO string, default CURRENT_TIMESTAMP -
status
- We currently support a status of "paid" -
products
- Array of purchased products-
sku
- Product sku
-
Build an official integration
Are you building an official integration? Contact us (engineering@convertkit.com) to set up an integration and let us know the name we should use for the integration. I.e. Stripe. We will send you an integration_key. Collect the api_secret for the ConvertKit account and send it, the integration_key, and the rest of the information for the purchase in each request. https://developers.convertkit.com/#create-a-purchase
When passing product information, it is important to choose a “pid” that is unique for a product but not for a variant. Variants of the same product should have the same “pid”. The “lid” should be your identifier for the line item of the purchase. In the future, this will allow for more fine-grained control over updates. For example, when one item from a purchase is returned this would identify which one.
Currently, the status of a purchase is only recorded and we do not take any action on the status. You should only send us purchases that have been completed and paid.
We suggest importing your transaction history when a user first sets up a connection with your integration. Previous purchases can be sent with a transaction_time in the past.