NAV
shell

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

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

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

Optional parameters

Deprecated parameters

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

Optional parameters

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

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

Optional parameters

Deprecated parameters

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

Optional parameters

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

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

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

Optional parameters

Deprecated parameters

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

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

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

Optional parameters

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

Optional parameters

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

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

Optional parameters

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

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

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

Optional parameters

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

Optional parameters

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

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

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

Optional parameters

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

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

These are the available event types:

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

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

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

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

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

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

Optional parameters

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

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

Required for third party integrations

Are you building an integration? Please fill out this form and we will help you get set up.

Optional parameters

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.

shell