Getting started

Overview

Calls for ConvertKit API v3 are relative to the URL https://api.convertkit.com/v3/

API v3 is in active development.

Planning your integration

Sweet! You're building an integration with ConvertKit. We're thrilled that you want to add-on to our platform. But before you dive in and start slinging code, let's talk about the best way to integrate with ConvertKit.

How you setup your integration depends on what type of provider you are. Let's run through a few examples:

Email Capture. If your product is mostly for capturing new subscribers then you should integrate with forms in ConvertKit. So in OptinMonster when a subscriber opts-in they are subscriber to a form in ConvertKit.
E-Commerce. The most important thing for e-commerce customers is the ability to add a tag when a purchase is made. So when SamCart wrote their integration they have the ability to add or remove a subscriber from a tag after a purchase or refund.
Full Integration. If you want a more full integration with ConvertKit you can add support for forms, courses, and tags.

If you aren't sure how best to structure your integration, just reach out to our team. We'll be happy to help you design it.

Building a larger integration?

If you're working with a company that's building a large integration with ConvertKit, you will need to use an integration key. This key will help us triaging, troubleshooting and diagnosing potential issues with integrations, ensuring that your integration works perfectly for your customers. Please fill out this form to request an integration key.

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 using first_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 or desc: asc to list subscribers added oldest to newest, desc to list subscribers added newest to oldest. asc is the default order.
subscriber_state - active or cancelled: receive only active subscribers or cancelled subscribers
page - the page to retrieve. 50 results are returned per page.

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 using first_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 or desc: asc to list subscribers added oldest to newest, desc to list subscribers added newest to oldest. asc is the default order.
subscriber_state - active or cancelled: receive only active subscribers or cancelled subscribers
page - the page to retrieve. 50 results are returned per page.

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 - Page for paginated results
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 or desc)
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 125 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 125 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

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've just released new endpoints to create, manage, and send broadcasts. 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?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 all the broadcasts for your account.

Endpoint

GET /v3/broadcasts

Required parameters

api_secret - Your API secret key

Create 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 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 HTML content
description - An internal description of this broadcast
email_address - Sending email address; leave blank to use your account's default sending email address
email_layout_template - Name of the email template to use; leave blank to use your account's default email template
public - Specifies whether or not this is a public post
published_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 subject
thumbnail_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 key
broadcast_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 key
broadcast_id - The ID of the broadcast you want to update

Optional parameters

content - The broadcast's email HTML content
description - An internal description of this broadcast
email_address - Sending email address; leave blank to use your account's default sending email address
email_layout_template - Name of the email template to use; leave blank to use your account's default email template
public - Specifies whether or not this is a public post
published_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 subject
thumbnail_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 key
broadcast_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.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".

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 and the name do not change even when the label is updated.

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 is 1. 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.

Getting started

Overview

Planning your integration

Building a larger integration?

API Basics

API key

API secret key

Integration Key

Responses

Bad data

Rate limiting

Internal server errors

Account

Show the current account

Endpoint

Required parameters

Forms

List forms

Endpoint

Required parameters

Add subscriber to a form

Endpoint

Required parameters

Optional parameters

Deprecated parameters

List subscriptions to a form

Endpoint

Required parameters

Optional parameters

Sequences

List sequences

Endpoint

Required parameters

Add subscriber to a sequence

Endpoint

Required parameters

Optional parameters

Deprecated parameters

List subscriptions to a sequence

Endpoint

Required parameters

Optional parameters

Tags

List tags

Endpoint

Required parameters

Create a tag

Endpoint

Required parameters

Tag a subscriber

Endpoint

Required parameters

Optional parameters

Deprecated parameters

Remove tag from a subscriber

Endpoint

Required parameters

Remove tag from a subscriber by email

Endpoint

Required parameters

List subscriptions to a tag

Endpoint

Required parameters

Optional parameters

Subscribers

List subscribers

Endpoint

Required parameters

Optional parameters

View a single subscriber

Endpoint

Required parameters

Update subscriber

Endpoint

Required parameters

Optional parameters

Unsubscribe subscriber

Endpoint

Required parameters

List tags for a subscriber