Guides
Upgrading to V4
Helping you upgrade from V3 of the API to V4
General updates
- The URLs for the API endpoints are now
api.kit.com/v4/...
instead ofapi.convertkit.com/v3/...
. They are otherwise unchanged unless called out specifically below. - V4 supports OAuth for applications and API Keys for automating simple tools and integrations for your personal account. V4 API Keys are not compatiblewith V3
- Our pagination mechanism has changed. We no longer support page or offset based pagination. All of our pagination is now cursor based. This improves performance.
- All errors are now returned with a consistent response shape. The response is a JSON object with a single attribute
errors
, an array of strings. - See below for a list of endpoints changed
Endpoint specific updates
Accounts
- Get current account
- The response shape has changed. User and account information is now nested under
user
andaccount
objects, respectively.
- The response shape has changed. User and account information is now nested under
Broadcasts
- List broadcasts
- The
page
parameter is no longer supported. To request next or previous pages, use thebefore
orafter
cursor
- The
- Create a broadcast
- The
email_layout_template
param is no longer supported. To specify the email template, use theemail_template_id
param.- Query your email templates to get the correct id
- The response shape has changed. We no longer return
email_layout_template
and return an object foremail_template
. - The error response shape has changed.
- The
- Get a broadcast
- The response shape has changed. We no longer return
email_layout_template
and return an object foremail_template
. - The error response shape has changed.
- The response shape has changed. We no longer return
- Delete a broadcast
- The response shape has changed. We return a 204 empty response.
- The error response shape has changed.
- Update a broadcast
- The
email_layout_template
param is no longer supported. To specify the email template, use theemail_template_id
param.- Query your email templates to get the correct id
- The response shape has changed. We no longer return
email_layout_template
and return an object foremail_template
. - The error response shape has changed.
- The
- Get stats
- The error response shape has changed.
Subscribers
- List subscribers
- The
page
parameter is no longer supported. To request next or previous pages, use thebefore
orafter
cursor - The
from
parameter is no longer supported. It has been replaced withcreated_after
. - The
to
parameter is no longer supported. It has been replaced withcreated_before
. - The
updated_from
parameter is no longer supported. It has been replaced withupdated_after
. - The
updated_to
parameter is no longer supported. It has been replaced withupdated_before
.
- The
- Get a subscriber
- The error response shape has changed.
- Update a subscriber
- The error response shape has changed.
- Unsubscribe a subscriber
- The URL path has changed.
/v3/unsubscribe
->/v4/subscribers/:id/unsubscribe
- We now require you to unsubscribe the subscriber via their id
- If you need to find their id by email address, you can query with List subscribers,
/v4/subscribers?email_address=<email>
- If you need to find their id by email address, you can query with List subscribers,
- The response shape has changed. It returns a 204 empty response instead of the subscriber.
- The error response shape has changed.
- The URL path has changed.
- List tags for a subscriber
- The response shape has changed.
created_at
has been replaced withtagged_at
. - The error response shape has changed.
- The response shape has changed.
Custom Fields
- Create a custom field
- The response shape has changed. The created custom field is now returned nested under a
custom_field
attribute. - This endpoint no longer allows creating multiple custom fields. Use Bulk create custom fields instead.
- The error response shape has changed.
- The response shape has changed. The created custom field is now returned nested under a
- Update a custom field
- The response shape has changed. The updated custom field is returned nested under a
custom_field
attribute. - The error response shape has changed.
- The response shape has changed. The updated custom field is returned nested under a
Forms
- List forms
- Add subscriber to a form by email address
- The
email
parameter is no longer supported. To add a subscriber by email address, use theemail_address
parameter.
- The
- List subscribers to a form
- The URL path has changed.
/v3/forms/:id/subscriptions
->/v4/forms/:id/subscribers
- The response shape has changed. Subscriber information is no longer nested under
subscription
.
- The URL path has changed.
Purchases
- List purchases
- The
page
parameter is no longer supported. To request next or previous pages, use thebefore
orafter
cursor
- The
- Create a purchase
- The error response shape has changed.
Sequences
- List sequences
- The response shape has changed. Sequences are nested under a
sequences
attributes (instead of acourses
attribute).
- The response shape has changed. Sequences are nested under a
- Add subscriber to a sequence by email address
- The
email
parameter is no longer supported. To add a subscriber by email address, use theemail_address
parameter.
- The
- List subscribers to a sequence
- The URL path has changed.
/v3/sequences/:id/subscriptions
->/v4/sequences/:id/subscribers
- The response shape has changed. Subscriber information is no longer nested under
subscription
.
- The URL path has changed.
Tags
- Create a tag
- The request shape has changed. Root
tag
attribute no longer required - The response shape has changed. The returned tag is nested under a
tag
attribute. - The error response shape has changed.
- This endpoint no longer allows creating multiple tags. Use Bulk create tags instead.
- The request shape has changed. Root
- List subscribers for a tag
- The URL path has changed.
/v3/tags/:id/subscriptions
->/v4/tags/:id/subscribers
- The
page
parameter is no longer supported. To request next or previous pages, use thebefore
orafter
cursor - The error response shape has changed.
- The response shape has changed. The root object is
subscribers
instead ofsubscriptions
along with other smaller changes.
- The URL path has changed.
- Tag a subscriber
- The URL path has changed.
/v3/tags/:id/subscribe
->/v4/tags/:tag_id/subscribers/:id
- The response shape has changed. The root object is
subscriber
instead ofsubscription
along with other smaller changes. - The error response shape has changed.
- None of the optional params from V3 are supported in V4
- The URL path has changed.
- Tag a subscriber by email address
- The URL path has changed.
/v3/tags/:id/subscribe
->/v4/tags/:tag_id/subscribers
- The
email
parameter is no longer supported. To add a subscriber by email address, use theemail_address
parameter. - The response shape has changed. The root object is
subscriber
instead ofsubscription
along with other smaller changes. - The error response shape has changed.
- None of the optional request params from V3 are supported in V4
- The URL path has changed.
- Remove tag from subscriber
- The URL path and HTTP verb has changed.
POST /v3/tags/:id/unsubscribe
->DELETE /v4/tags/:tag_id/subscribers/:id
- The response shape has changed. We return a 204 empty response
- The error response shape has changed.
- The URL path and HTTP verb has changed.
- Remove tag from subscriber by email address
- The URL path and HTTP verb has changed.
POST /v3/tags/:id/unsubscribe
->DELETE /v4/tags/:tag_id/subscribers/:id
- The response shape has changed. We return a 204 empty response.
- The error response shape has changed.
- The URL path and HTTP verb has changed.
Webhooks
- The URL paths for webhooks have changed from
/automations/hooks
to/webhooks
. - Create a webhook
- The response shape has changed. The root object is
webhook
instead ofrule
. - The error response shape has changed.
- The response shape has changed. The root object is
- Delete a webhook
- The response shape has changed. We return a 204 empty response.
- The error response shape has changed.