API Documentation (v2)

API

API calls for ConvertKit are directed to the subdomain api.convertkit.com

With the API you can:

  • Get a list of forms for an account
  • Subscribe to a form
  • Subscribe to a sequence
  • Add subscriber to an email sequence
  • Mark a subscriber as converted
  • Unsubscribe from a form
  • Unsubscribe from a sequence

PARAMS

  • api_key [k] - the api key of the account making the request
    • This is required for almost all API calls (exceptions are noted below)
  • version [v] - version of the api that you'd like to use (defaults to oldest version for compatibility)

FORMATS

Adding .json to the calls is not necessary as JSON is the assumed format.

e.g. https://api.convertkit.com/forms?k=f9922361d11e7339cc1cde3d54c071&v=1

Sequences

/courses?k=[api_key]

Example:

/courses/?k=f9922361d11e7339cc1cde3d54c071

Returns a list of sequences (formerly called courses) for the account specified by the api_key
[
 {
 id: 4,
 name: "Designing Web Applications",
 subscriber_count: 783,
 unsubscribe_count: 62,
 created_at: "2013-02-01T18:03:12Z",
 updated_at: "2013-11-09T11:51:01Z",
 details: "http://api.convertkit.dev/courses/4?k=f9922361d11e7339cc1cde3d54c071&v=1"
 },
 {
 id: 5,
 name: "Increasing Conversions",
 subscriber_count: 1697,
 unsubscribe_count: 206,
 created_at: "2013-02-01T18:03:19Z",
 updated_at: "2013-11-09T11:51:01Z",
 details: "http://api.convertkit.dev/courses/5?k=f9922361d11e7339cc1cde3d54c071&v=1"
 },
 ...
]

FORMS

 Forms are "subscription forms" in the world of ConvertKit. These calls are used by the original WordPress plugin to find the names of the subscription forms for an account.

Substitute "landing_pages" in place of "forms" to get a list of landing pages.

Get a list of forms for an account

GET /forms?k=[api_key]&v=[version]

Results are sorted alphabetically.

Version 2

GET /forms?k=f9922361d11e7339cc1cde3d54c071&v=2
[
 {
 id: 4316561,
 subscriber_count: 551,
 created_at: "2013-06-03T14:14:15Z",
 updated_at: "2013-06-03T14:16:51Z",
 name: "App Design Handbook sample chapter",
 details: "http://api.convertkit.dev/forms/4316561?k=f9922361d11e7339cc1cde3d54c071&v=2",
 embed: "http://api.convertkit.dev/forms/4316561/embed?k=f9922361d11e7339cc1cde3d54c071&v=2"
 },
 {
 id: 19273,
 subscriber_count: 753,
 created_at: "2013-03-26T18:00:56Z",
 updated_at: "2013-04-17T21:16:41Z",
 name: "Authority",
 details: "http://api.convertkit.dev/forms/19273?k=f9922361d11e7339cc1cde3d54c071&v=2",
 embed: "http://api.convertkit.dev/forms/19273/embed?k=f9922361d11e7339cc1cde3d54c071&v=2"
 },
 ...
]

Version 1

A version 1 call returns the following: Note: The plugin version 0.11 uses this format
[
 {
 landing_page: {
 id: 4316561,
 name: "App Design Handbook sample chapter"
 }
 },
 {
 landing_page: {
 id: 19273,
 name: "Authority"
 }
 },
 {
 landing_page: {
 id: 1265576,
 name: "Authority (Free Book)"
 }
 },
 ...
 ]

Subscribe to a Form

POST /forms/[formID]/subscribe?k=[api_key]&email=[email]&fname=[first_name]&[course_opted=true]

Params

  • api_key
  • email - email address of new subscriber
  • fname - [optional, but recommended] first name of new subscriber
  • course_opted - [optional] if present will subscribe user to sequence if sequence is attached to form/landing_page

Returns

On Success:
{
 status: "created",
 form: "App Design Handbook sample chapter",
 created_at: "2013-12-05T21:15:05Z",
 subscription_status: "active",
 email: "bsharpe@gmail.com",
 fname: "Ben",
 course_opted: false
 }
  • status
  • form - the form the user was subscribed to
  • subscription_status - the status of a subscription
    • inactive - user is new and hasn't confirmed yet
    • active - user is subscribed and confirmed (this will be returned if a user is subscribed more than once)
  • email - the email passed in
  • fname - first name passed in
  • course_opted - whether the user was opted into the sequence
On Error:
{
 status: 'bad parameter'
 }

If no email is passed in, you'll get a bad parameter error.

Form Details

Version 2

GET /forms/[formID]?k=[api_key]&v=2
Example:
GET /forms/4?k=f9922361d11e7339cc1cde3d54c071&v=2
{
 id: 4,
 title: "Download a free guide on Designing Forms That Convert",
 description: "It's free, so just enter your email address and the PDF will be sent directly to your inbox.",
 button_msg: "Send Me The Free Guide",
 success_msg: "Sweet! I'm glad you're interested in increasing conversions. Enjoy the free PDF, then I hope you find the email course helpful. I put my best content in there. Talk soon, Nathan",
 created_at: "2013-02-01T20:32:38Z",
 updated_at: "2013-02-19T17:58:35Z",
 course_prompt: "I'd like to receive a free 30 email day course on increasing conversion rates.",
 image: "http://s3.amazonaws.com/convertkit/subscription_forms/images/000/000/004/standard/book.jpg?1361296547"
 }
  • course_prompt will be null if there is no sequence to opt into.
  • image will be null if there is no image.

Version 1

GET /forms/[formID]?k=[api_key]&v=1

Example:

GET /forms/4?k=f9922361d11e7339cc1cde3d54c071&v=1
{
 subscription_form: {
 title: "Download a free guide on Designing Forms That Convert",
 description: "It's free, so just enter your email address and the PDF will be sent directly to your inbox.",
 sign_up_button_text: "Send Me The Free Guide",
 success_message: "Sweet! I'm glad you're interested in increasing conversions. Enjoy the free PDF, then I hope you find the email course helpful. I put my best content in there. Talk soon, Nathan",
 id: 4,
 course_opt_in_prompt: "I'd like to receive a free 30 email day course on increasing conversion rates.",
 image: {
 url: "http://s3.amazonaws.com/convertkit/subscription_forms/images/000/000/004/standard/book.jpg?1361296547"
 },
 landing_page: {
 course: true
 }
 }
 }

Add subscriber to an email course

<code>POST /courses/[id]/subscribe?k=[api_key]&email=[email]&fname=[first_name]

Params

  • id – id of the sequence
  • api_key
  • email – email address of new subscriber
  • fname – [optional, but recommended] first name of new subscriber

Returns

On Success:
<code>{
  "status": "created",
  "course": "Designing Web Applications",
  "created_at": "2015-01-09T12:02:16Z",
  "subscription_status": "active"
}
  • status
  • course – the sequence the user was subscribed to
  • subscription_status – the status of a subscription
    • inactive – user is new and hasn’t confirmed yet
    • active – user is subscribed and confirmed (this will be returned if a user is subscribed more than once)
On Error:
<code>{
  "status": "bad parameter"
}

Mark a subscriber as converted

<code>POST /courses/[id]/convert?k=[api_key]&email=[email]

Params

  • id – id of the sequence
  • api_key
  • email – email address of new subscriber

Returns

On Success:
<code>{
  "status": "ok",
  "course": "Designing Web Applications",
  "email": "test@example.com",
  "state": "converted"
}
  • status
  • course – the sequence the user was subscribed to
  • email – the email passed in
  • state – the status of a subscription (converted)
On Error:
<code>{
  "status": "not found",
  "email": "notfound@example.com"
}
  • status
    • bad parameter – error with some of the parameters
    • email – subscriber was not found
  • email – the email passed in

Unsubscribe from a sequence

<code>POST /courses/[id]/unsubscribe?k=[api_key]&email=[email]

Params

  • id – id of the sequence
  • api_key
  • email – email address of subscriber

Returns

On Success:
<code>{
  "status": "ok",
  "email": "test@example.com",
  "course": "Designing Web Applications",
  "subscription_status": "cancelled"
}
  • status
  • course – the sequence the user was unsubscribed from
  • subscription_status – the status of a subscription
    • cancelled – user has been unsubscribed
On Error:
<code>{
  "status": "bad parameter"
}

Unsubscribe from a form

<code>POST /forms/[id]/unsubscribe?k=[api_key]&email=[email]

Params

  • id – id of the form
  • api_key
  • email – email address of subscriber

Returns

On Success:
<code>{
  "status": "ok",
  "email": "test@example.com",
  "form": "Designing Web Applications",
  "subscription_status": "cancelled"
}
  • status
  • form – the form the user was unsubscribed from
  • subscription_status – the status of a subscription
    • cancelled – user has been unsubscribed
On Error:
<code>{
  "status": "bad parameter"
}

Still need help? Contact Us Contact Us