Changelog

ConvertKit API V4 introduces many new features and improved functionality from our previous versions.

• Improved performance
• Cursor-based pagination
• Bulk requests and async processing
• New functionality for broadcasts, including access to subscriber filters and improved HTML support
• Bug fixes

Breaking changes V3 -> V4

URLs

The URLs for the API endpoints are now api.convertkit.com/v4/... instead of api.convertkit.com/v3/.... They are otherwise unchanged unless called out specifically below.

Authentication

We currently only support OAuth for V4. If you're unable to implement OAuth, continue using V3.

Pagination

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.

Errors

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.

Accounts

Get current account

• The response shape has changed. User and account information is now nested under user and account objects, respectively.

Broadcasts

List broadcasts

• The page parameter is no longer supported. To request next or previous pages, use the before or after cursor

Create a broadcast

• The email_layout_template param is no longer supported. To specify the email template, use the email_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 for email_template.
• The error response shape has changed.

Get a broadcast

• The response shape has changed. We no longer return email_layout_template and return an object for email_template.
• The error response shape has changed.

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 the email_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 for email_template.
• The error response shape has changed.

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 the before or after cursor
• The from parameter is no longer supported. It has been replaced with created_after.
• The to parameter is no longer supported. It has been replaced with created_before.
• The updated_from parameter is no longer supported. It has been replaced with updated_after.
• The updated_to parameter is no longer supported. It has been replaced with updated_before.

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>
• The response shape has changed. It returns a 204 empty response instead of the subscriber.
• The error response shape has changed.

List tags for a subscriber

• The response shape has changed. created_at has been replaced with tagged_at.
• The error 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.

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.

Forms

List forms

• The response shape has changed.

Add subscriber to a form by email address

• The email parameter is no longer supported. To add a subscriber by email address, use the email_address parameter.

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.

Purchases

List purchases

• The page parameter is no longer supported. To request next or previous pages, use the before or after cursor

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 a courses attribute).

Add subscriber to a sequence by email address

• The email parameter is no longer supported. To add a subscriber by email address, use the email_address parameter.

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.

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.

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 the before or after cursor
• The error response shape has changed.
• The response shape has changed. The root object is subscribers instead of subscriptions along with other smaller changes.

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 of subscription along with other smaller changes.
• The error response shape has changed.
• None of the optional params from V3 are supported in V4

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 the email_address parameter.
• The response shape has changed. The root object is subscriber instead of subscription along with other smaller changes.
• The error response shape has changed.
• None of the optional request params from V3 are supported in V4

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.

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.

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 of rule.
• The error response shape has changed.

Delete a webhook

• The response shape has changed. We return a 204 empty response.
• The error response shape has changed.