Kit Developer Documentation

API V3 is deprecated and no longer in active development. Use API V4 for new projects, and see Upgrading to V4 to move an existing integration.

Forms are used to collect subscriber information and can be embedded on your website or used as hosted landing pages.

List forms

Returns a list of all the forms for your account.

Endpoint

GET /v3/forms

Parameters

string

required

Your account API key

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

{
  "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."
    }
  ]
}

Add subscriber to a form

Subscribe an email address to one of your forms. Archived, deleted and restricted forms, and archived legacy landing pages, no longer accept subscribers. The request returns 404, the same response as for a form that does not exist.

Endpoint

POST /v3/forms/#{form_id}/subscribe

Parameters

string

required

Your account API key

integer

required

The ID for the form you want to add the subscriber to

string

required

Subscriber email address

string

Subscriber first name

object

Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.

array

Array of tag ids to subscribe to

Deprecated Parameters

array

Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly.

array

Array of form ids to subscribe to. You should add the subscriber to each form individually. Only legacy landing page IDs are resolved; archived ones are skipped.

string

Subscriber first name. You should prefer using first_name listed above.

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"
         }'

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]
         }'

{
  "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
    }
  }
}

List subscriptions to a form

List subscriptions to a form including subscriber data.

Endpoint

GET /v3/forms/#{form_id}/subscriptions

Parameters

string

required

Your API secret key

integer

required

The ID for the form you want to list subscribers from

string

Sort order for results (asc or desc). asc to list subscribers added oldest to newest, desc to list subscribers added newest to oldest. Default is asc.

string

Filter by subscriber state (active or cancelled). Receive only active subscribers or cancelled subscribers.

string

The page of results being requested. Default value is 1. Each page of results will contain up to 50 subscriptions.

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

{
  "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"
        }
      }
    }
  ]
}

Getting Started

Endpoints

Forms

List forms

Endpoint

Parameters

Add subscriber to a form

Endpoint

Parameters

Deprecated Parameters

List subscriptions to a form

Endpoint

Parameters