Skip to main content

ConvertKit

This page guides you through setting up the ConvertKit source connector, which syncs data from Kit (formerly ConvertKit) using the Kit API v4.

Prerequisites​

  • A Kit account on a plan that's eligible for API access.
  • One of the following sets of credentials:
    • A Kit V4 API key. API keys only access your own Kit account and have a lower rate limit than OAuth.
    • OAuth 2.0 credentials from a Kit app: a Client ID, Client Secret, and Refresh Token. OAuth is required to sync the purchases stream.

Kit V3 API keys and API secrets don't work with the V4 API. If you only have V3 credentials, create a V4 API key.

Setup guide​

Step 1: Get your Kit credentials​

Option A: API key​

  1. In Kit, go to Settings > Developer.
  2. Create a new V4 API key.
  3. Copy the API key and store it somewhere safe. Kit only shows the key once. If you lose it, you must reset the key.

For more details, see Creating V4 API keys.

Option B: OAuth 2.0​

  1. Create a Kit app and turn on API access for it.
  2. Configure the app's redirect URI, then copy the app's Client ID and Client Secret.
  3. Complete Kit's OAuth authorization code flow for the Kit account you want to sync, and save the Refresh Token that Kit returns.

The connector uses the refresh token to request access tokens from https://api.kit.com/oauth/token and stores the rotated refresh token in your connection configuration.

Step 2: Set up the ConvertKit connector in Airbyte​

  1. In Airbyte, go to Sources and select ConvertKit.
  2. Enter a name for the source.
  3. For Start date, enter the UTC date and time from which to sync subscriber records, in the format YYYY-MM-DDTHH:mm:ssZ. The default is 2013-01-01T00:00:00Z. The start date only applies to the subscribers, form_subscribers, sequence_subscribers, and tag_subscribers streams.
  4. For Authentication Type, choose one of the following:
    • API Key: Enter your V4 API key.
    • OAuth 2.0: Enter your Client ID, Client Secret, and Refresh Token. You can leave Access Token and Access Token Expires At empty. The connector fills them in when it refreshes the token.
  5. Click Set up source.

Supported sync modes​

FeatureSupported?Notes
Full Refresh SyncYes
Incremental SyncYessubscribers, form_subscribers, sequence_subscribers, and tag_subscribers only

Supported streams​

StreamKit API endpointPrimary keyIncremental
broadcastsList broadcastsidNo
current_accountGet current accountNoneNo
custom_fieldsList custom fieldsidNo
email_templatesList email templatesidNo
formsList formsidNo
form_subscribersList subscribers for a formid, form_idYes
purchasesList purchasesidNo
segmentsList segmentsidNo
sequencesList sequencesidNo
sequence_subscribersList subscribers for a sequenceid, sequence_idYes
subscribersList subscribersidYes
tagsList tagsidNo
tag_subscribersList subscribers for a tagid, tag_idYes

The form_subscribers, sequence_subscribers, and tag_subscribers streams read every form, sequence, or tag first, then request the subscribers for each one. The connector adds form_id, sequence_id, or tag_id to each record.

The subscriber streams request subscribers in all states, including inactive, bounced, complained, and cancelled subscribers, not only active ones.

Incremental sync behavior​

  • subscribers: Filters on the subscriber's last update time (updated_after). The cursor field, date_last_loaded, is added by the connector and records when the sync read the record.
  • tag_subscribers: Filters on when the subscriber was tagged (tagged_after). The cursor field, date_loaded, is added by the connector and records when the sync read the record.
  • form_subscribers and sequence_subscribers: Filter on when the subscriber was added (added_after), using the added_at field as the cursor.

Each incremental sync re-reads the last hour before the saved cursor, so expect some duplicate records unless you use a deduplicating sync mode.

Limitations and troubleshooting​

Rate limits​

Kit's rate limits allow 120 requests per API key and 600 requests per OAuth access token in a 60-second period. When Kit returns HTTP 429, Airbyte backs off and retries the request. Use OAuth if your syncs are slow because of rate limiting.

purchases requires OAuth​

Kit's List purchases endpoint only accepts OAuth access tokens. If you authenticate with an API key and select the purchases stream, the sync fails with an error. Switch to OAuth 2.0 or deselect the purchases stream.

Connections created before version 0.3.0​

Versions before 0.3.0 used the Kit V3 API and authenticated with a V3 API secret. Starting with 0.3.0, the connector uses the V4 API. It still falls back to the stored V3 secret if no API key is set, but Kit doesn't accept V3 credentials on the V4 API. If your sync fails with 401 The API key is invalid, create a V4 API key and enter it under Authentication Type > API Key.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
object
credentials
string
start_date
Legacy API Secret
string
api_secret

Changelog​

Expand to review
VersionDatePull RequestSubject
0.3.72026-11-1091329Upgrade to source-declarative-manifest base image 7.47.0.
0.3.62026-11-0490942Simplify purchases error handling without changing authentication errors or retries.
0.3.52026-10-1378649Update dependencies
0.3.42026-10-1288414Mark api_secret as airbyte_secret and retitle it Legacy API Secret
0.3.32025-05-2460414Update dependencies
0.3.22025-05-1159955Update dependencies
0.3.12025-05-0459410Update dependencies
0.3.02025-04-2858617Update to Kit API v4, add OAuth support, add 8 additional streams, update schemas
0.2.232025-04-2758849Update dependencies
0.2.222025-04-1958341Update dependencies
0.2.212025-04-1257808Update dependencies
0.2.202025-04-0557198Update dependencies
0.2.192025-03-2956524Update dependencies
0.2.182025-03-2255951Update dependencies
0.2.172025-03-0855270Update dependencies
0.2.162025-03-0154976Update dependencies
0.2.152025-02-2254379Update dependencies
0.2.142025-02-1553751Update dependencies
0.2.132025-02-0853342Update dependencies
0.2.122025-02-0152823Update dependencies
0.2.112025-01-2552332Update dependencies
0.2.102025-01-1851673Update dependencies
0.2.92025-01-1151107Update dependencies
0.2.82024-12-2850522Update dependencies
0.2.72024-12-2150066Update dependencies
0.2.62024-12-1449510Update dependencies
0.2.52024-12-1248958Update dependencies
0.2.42024-11-0448217Update dependencies
0.2.32024-10-2947764Update dependencies
0.2.22024-10-2847619Update dependencies
0.2.12024-08-1644196Bump source-declarative-manifest version
0.2.02024-08-1544161Refactor connector to manifest-only format
0.1.142024-08-1243803Update dependencies
0.1.132024-08-1043503Update dependencies
0.1.122024-08-0343237Update dependencies
0.1.112024-07-2742643Update dependencies
0.1.102024-07-2042363Update dependencies
0.1.92024-07-1341742Update dependencies
0.1.82024-07-1041405Update dependencies
0.1.72024-07-0941272Update dependencies
0.1.62024-07-0640860Update dependencies
0.1.52024-06-2540282Update dependencies
0.1.42024-06-2239989Update dependencies
0.1.32024-06-1739505Make compatible with builder
0.1.22024-06-0639299[autopull] Upgrade base image to v1.2.2
0.1.12024-05-2138492[autopull] base image + poetry + up_to_date
0.1.02022-10-2518455Initial commit