[GET] ConvertKit API – Scam

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, please fill out this form to get an integration key. We’ll work with you to ensure your integration works amazingly for our mutual customers.

Using an integration key will allow your integration to access specific features of our API, and we’ll be able to work with you to set custom rate limiting.

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

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

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.

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 account API key.

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 fields (the custom field 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 descasc 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

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 fields (the custom field 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 descasc 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

Example request

curl https://api.convertkit.com/v3/tags?api_key=<your_public_api_key>

Example response


  "tags": [
    
      "id": 1,
      "name": "House Stark",
      "created_at": "2016-02-28T08:07:00Z"
    ,
    
      "id": 2,
      "name": "House Lannister",
      "created_at": "2016-02-28T08:07:00Z"
    
  ]

Returns a list of tags for the account.

Endpoint

GET /v3/tags

Required parameters

  • api_key – Your account API key.

Create a tag

Example request


Single tag

curl -X POST https://api.convertkit.com/v3/tags
     -H 'Content-Type: application/json'
     -d ' "api_key": "<your_public_api_key>",
           "tag": 
             "name": "Example Tag"
            '

Multiple tags

curl -X POST https://api.convertkit.com/v3/tags
     -H 'Content-Type: application/json'
     -d ' "api_key": "<your_public_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 receive a JSON array with the same type of objects:

[
  "account_id": 1,
  "created_at": "2017-04-12T11:10:32Z",
  "deleted_at": null,
  "id": 1,
  "name": "Example Tag",
  "state": "available",
  "updated_at": "2017-04-12T11:10:32Z"
,

  "account_id": 1,
  "created_at": "2017-04-12T11:11:566Z",
  "deleted_at": null,
  "id": 1,
  "name": "Example Tag 2",
  "state": "available",
  "updated_at": "2017-04-12T11:11:566Z"
]

Endpoint

POST /v3/tags

Required parameters

  • api_key – Your account API key.
  • tag – a JSON object or an array of JSON objects, respectively, that include the tag name
    • "name": "Example Tag"

Tag a subscriber

Example request

curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/subscribe
     -H "Content-Type: application/json; charset=utf-8"
     -d ' 
            "api_key": "<your_public_api_key>",
            "email": "jonsnow@example.com"
         '

Example response


  "subscription": 
    "id": 3,
    "state": "inactive",
    "created_at": "2016-02-28T08:07:00Z",
    "source": null,
    "referrer": null,
    "subscribable_id": 1,
    "subscribable_type": "tag",
    "subscriber": 
      "id": 1
    
  

Tags are handled as subscriptions. Subscribe an email address to a tag to have that tag applied to the subscriber with that email address.

Endpoint

POST /v3/tags/#tag_id/subscribe

Required parameters

  • api_key – Your account API key.
  • email – Subscriber email address.

Optional parameters

  • first_name – Subscriber first name.
  • fields – Object of key/value pairs for custom fields (the custom field must exist before you can use it here).
  • tags – Array of tag ids to subscribe to.

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

  • api_secret – Your api secret key.

Remove tag from a subscriber by email

Example request

curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/unsubscribe
    -H "Content-Type: application/json; charset=utf-8"
    -d ' 
          "api_secret": "<your_secret_api_key>",
          "email": "jonsnow@example.com"
        '

Example response


  "id": 1,
  "name": "House Stark",
  "created_at": "2016-02-28T08:07:00Z"

Endpoint

POST /v3/tags/#tag_id/unsubscribe

Required parameters

  • api_secret – Your api secret key.
  • email – Subscriber email address.

List subscriptions to a tag

Example request


curl https://api.convertkit.com/v3/tags/<tag_id>/subscriptions?api_secret=<your_secret_api_key>

Example response


  "total_subscriptions": 2,
  "page": 1,
  "total_pages": 1,
  "subscriptions": [
    
      "id": 1,
      "state": "active",
      "created_at": "2016-02-28T08:07:00Z",
      "source": null,
      "referrer": null,
      "subscribable_id": 1,
      "subscribable_type": "tag",
      "subscriber": 
        "id": 1,
        "first_name": "Jon",
        "email_address": "jonsnow@example.com",
        "state": "active",
        "created_at": "2016-02-28T08:07:00Z",
        "fields": 
          "last_name": "Snow"
        
      ,
    ,
    
      "id": 2,
      "state": "active",
      "created_at": "2016-02-27T08:07:00Z",
      "source": null,
      "referrer": null,
      "subscribable_id": 1,
      "subscribable_type": "tag",
      "subscriber": 
        "id": 2,
        "first_name": "Arya",
        "email_address": "arya@example.com",
        "state": "active",
        "created_at": "2016-02-27T08:07:00Z",
        "fields": 
          "last_name": "Stark"
        
      ,
    
  ]

List subscriptions to a tag including subscriber data.

Endpoint

GET /v3/tags/#tag_id/subscriptions

Required parameters

  • api_secret – your api secret key

Optional parameters

  • sort_order – asc or descasc 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

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 fields for your subscriber as object of key/value pairs (the custom field 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.

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.

Get stats

Get the stats (recipient count, open rate, click rate, unsubscribe count, total clicks, status, send progress) from a specific broadcast.

Endpoint

GET /v3/broadcasts/#broadcast_id/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
      
    
  ]

Required parameters

  • api_secret – Your account API secret key.
  • broadcast_id – the id number of the broadcast you want to target

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.

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 label

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 labels

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.

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
  • products.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.
  • products.lid – Each product should have an lid that is unique to the product for this purchase. If you have ‘line items’, lid is where you would put your identifier for each line item.

Required for third party integrations

Are you building an integration? Contact us and we will help you get set up.

  • purchase.integration – The name of your integration (i.e. eBay)
  • integration_key – An access token for authenticating 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
  • currency – 3 letter currency code, default USD
  • 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
    • name – Product name
    • pid – Your unique product identifier. Product variants should have the same pid
    • lid – Your identifier for the product in this specific purchase. i.e. A line item identifier
    • sku – Product sku
    • unit_price – Product price
    • quantity – Product quantity

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.

[GET] ConvertKit API – Scam
4.9 (98%) 32 votes