NAV Navbar
shell
  • Getting started
  • Account
  • Forms
  • Sequences
  • Tags
  • Subscribers
  • Broadcasts
  • Webhooks
  • Custom Fields
  • Purchases
  • 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:

    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

    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 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

    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 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

    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'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?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: 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

    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".

    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 }}.

    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.