ConvertKit

Manage ConvertKit subscribers, forms, tags, and sequences

Overview

Works with the email marketing resources in your ConvertKit account: custom fields, forms, sequences (ConvertKit’s autoresponder courses), tags, and the subscribers attached to a tag. Create, update, delete and list custom fields; subscribe an email address to a form or a sequence, optionally carrying a first name, tags and custom field values; list your forms, sequences and tags; read the subscriptions behind any of them; and add or remove a tag on a subscriber. Every list operation can either return everything or stop at a limit you set.

Category: Marketing
Tool Name: convertkit
Version: 1

Appearance: Icon: lucide-Mail | Color: #FB6970

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires ConvertKit API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Custom Field	customField
Form	form
Sequence	sequence
Tag	tag
Tag Subscriber	tagSubscriber

Operations

The operations available depend on the resource you select.

Custom Field

Operation	Value	Description
Create	create	Create a field
Delete	delete	Delete a field
Get Many	getAll	Get many fields
Update	update	Update a field

Form

Operation	Value	Description
Add Subscriber	addSubscriber	Add a subscriber
Get Many	getAll	Get many forms
Get Subscriptions	getSubscriptions	List subscriptions to a form including subscriber data

Sequence

Operation	Value	Description
Add Subscriber	addSubscriber	Add a subscriber
Get Many	getAll	Get many sequences
Get Subscriptions	getSubscriptions	Get all subscriptions to a sequence including subscriber data

Tag

Operation	Value	Description
Create	create	Create a tag
Get Many	getAll	Get many tags

Tag Subscriber

Operation	Value	Description
Add	add	Add a tag to a subscriber
Get Many	getAll	List subscriptions to a tag including subscriber data
Delete	delete	Delete a tag from a subscriber

Parameters

Custom Field: Create

Parameter	Type	Required	Default	Description
Label	string	Yes	—	The label of the custom field. Supports expressions.

Custom Field: Delete

Parameter	Type	Required	Default	Description
Field ID	string	Yes	—	The ID of your custom field. Supports expressions.

Custom Field: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Max number of results to return. (shown when Return All is false)

Custom Field: Update

Parameter	Type	Required	Default	Description
Field ID	string	Yes	—	The ID of your custom field. Supports expressions.
Label	string	Yes	—	The label of the custom field. Supports expressions.

Form: Add Subscriber

Parameter	Type	Required	Default	Description
Form ID	string	Yes	—	The form ID. Find it in your ConvertKit account under Forms. Supports expressions.
Email	string	Yes	—	The subscriber’s email address. Supports expressions.
Additional Fields	collection	No	{}	Optional subscriber details to send with the subscription.
— Custom Fields	fixedCollection	No	{}	Object of key/value pairs for custom fields (the custom field must exist before you can use it here).
— — Field Key	string	No	—	The field’s key.
— — Field Value	string	No	—	Value of the field.
— First Name	string	No	—	The subscriber’s first name.
— Tag IDs	string	No	—	Comma-separated tag IDs to apply to the subscriber. Find tag IDs in your ConvertKit account.

Form: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Max number of results to return. (shown when Return All is false)

Form: Get Subscriptions

Parameter	Type	Required	Default	Description
Form ID	string	Yes	—	The form ID. Find it in your ConvertKit account under Forms. Supports expressions.
Additional Fields	collection	No	{}	Receive only active subscribers or cancelled subscribers.
— Subscriber State	options	No	active	Which subscriptions to return.
				Options: active, cancelled
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Max number of results to return. (shown when Return All is false)

Sequence: Add Subscriber

Parameter	Type	Required	Default	Description
Sequence ID	string	Yes	—	The sequence ID. Find it in your ConvertKit account under Sequences. Supports expressions.
Email	string	Yes	—	The subscriber’s email address. Supports expressions.
Additional Fields	collection	No	{}	Optional subscriber details to send with the subscription.
— Custom Fields	fixedCollection	No	{}	Object of key/value pairs for custom fields (the custom field must exist before you can use it here).
— — Field Key	string	No	—	The field’s key.
— — Field Value	string	No	—	Value of the field.
— First Name	string	No	—	The subscriber’s first name.
— Tag IDs	string	No	—	Comma-separated tag IDs to apply to the subscriber. Find tag IDs in your ConvertKit account.

Sequence: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Max number of results to return. (shown when Return All is false)

Sequence: Get Subscriptions

Parameter	Type	Required	Default	Description
Sequence ID	string	Yes	—	The sequence ID. Find it in your ConvertKit account under Sequences. Supports expressions.
Additional Fields	collection	No	{}	Receive only active subscribers or cancelled subscribers.
— Subscriber State	options	No	active	Which subscriptions to return.
				Options: active, cancelled
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Max number of results to return. (shown when Return All is false)

Tag: Create

Parameter	Type	Required	Default	Description
Name	string	Yes	—	Tag name, multiple can be added separated by comma. Supports expressions.

Tag: Get Many

Parameter	Type	Required	Default	Description
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Max number of results to return. (shown when Return All is false)

Tag Subscriber: Add

Parameter	Type	Required	Default	Description
Tag ID	string	Yes	—	The tag ID. Find it in your ConvertKit account under Subscribers > Tags, or use the Tag: Get Many operation. Supports expressions.
Email	string	Yes	—	Subscriber email address. Supports expressions.
Additional Fields	collection	No	{}	Optional subscriber details to send with the tag.
— Custom Fields	fixedCollection	No	{}	Object of key/value pairs for custom fields (the custom field must exist before you can use it here).
— — Field Key	string	No	—	The field’s key.
— — Field Value	string	No	—	Value of the field.
— First Name	string	No	—	Subscriber first name.

Tag Subscriber: Get Many

Parameter	Type	Required	Default	Description
Tag ID	string	Yes	—	The tag ID. Find it in your ConvertKit account under Subscribers > Tags, or use the Tag: Get Many operation. Supports expressions.
Additional Fields	collection	No	{}	Receive only active subscribers or cancelled subscribers.
— Subscriber State	options	No	active	Which subscriptions to return.
				Options: active, cancelled
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	100	Max number of results to return. (shown when Return All is false)

Tag Subscriber: Delete

Parameter	Type	Required	Default	Description
Tag ID	string	Yes	—	The tag ID. Find it in your ConvertKit account under Subscribers > Tags, or use the Tag: Get Many operation. Supports expressions.
Email	string	Yes	—	Subscriber email address. Supports expressions.

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

How the output item is built depends on whether ConvertKit answers with a single record or a list.

• Single-record operations merge the response onto the input item JSON — the incoming fields pass through and same-named response fields replace them. One output item per input item.
• List operations replace the item JSON. Each record in the list becomes its own output item carrying that record’s fields only; the input JSON does not pass through. An empty list produces no output items for that input item.

Binary data on the input item is forwarded in both cases.

Operation	Output items	Item JSON
Custom Field: Create	one per input item	Input JSON merged with the created field
Custom Field: Update	one per input item	Input JSON merged with success: true — ConvertKit’s own response body is not passed through
Custom Field: Delete	one per input item	Input JSON merged with the delete response, which is empty when ConvertKit replies with no content
Custom Field: Get Many	one per custom field	The custom field record
Form: Add Subscriber	one per input item	Input JSON merged with the subscription record
Form: Get Many	one per form	The form record
Form: Get Subscriptions	one per subscription	The subscription record, including its subscriber data
Sequence: Add Subscriber	one per input item	Input JSON merged with the subscription record
Sequence: Get Many	one per sequence	The sequence record
Sequence: Get Subscriptions	one per subscription	The subscription record, including its subscriber data
Tag: Create	one per tag returned, or one per input item when ConvertKit answers with a single object	The response ConvertKit sends for the tags you created
Tag: Get Many	one per tag	The tag record
Tag Subscriber: Add	one per input item	Input JSON merged with the subscription record
Tag Subscriber: Get Many	one per subscription	The subscription record, including its subscriber data
Tag Subscriber: Delete	one per input item	Input JSON merged with the unsubscribe response

The fields inside each record are the ones the ConvertKit v3 API returns for that resource. Reference them downstream by expression, for example {{ $json.id }}.

Usage Examples

• subscribe an email to a ConvertKit form
• list all ConvertKit tags
• create a custom field in ConvertKit
• add a tag to a subscriber in ConvertKit
• get all subscribers for a ConvertKit sequence
• remove a tag from a subscriber

Example Configuration

Subscribe an incoming email address to a form, with a first name, two tags and a custom field value:

{
  "type": "convertkit",
  "parameters": {
    "resource": "form",
    "operation": "addSubscriber",
    "id": "123456",
    "email": "{{ $json.email }}",
    "additionalFields": {
      "firstName": "{{ $json.firstName }}",
      "tags": "456,789",
      "fieldsUi": {
        "fieldsValues": [
          {
            "key": "company",
            "value": "{{ $json.company }}"
          }
        ]
      }
    }
  }
}

Start a subscriber on a sequence:

{
  "type": "convertkit",
  "parameters": {
    "resource": "sequence",
    "operation": "addSubscriber",
    "id": "789012",
    "email": "{{ $json.email }}",
    "additionalFields": {
      "firstName": "{{ $json.firstName }}"
    }
  }
}

List the active subscriptions behind a form, fifty at a time:

{
  "type": "convertkit",
  "parameters": {
    "resource": "form",
    "operation": "getSubscriptions",
    "id": "123456",
    "returnAll": false,
    "limit": 50,
    "additionalFields": {
      "subscriberState": "active"
    }
  }
}

Create three tags in one call:

{
  "type": "convertkit",
  "parameters": {
    "resource": "tag",
    "operation": "create",
    "name": "VIP Customer,Premium User,Beta Tester"
  }
}

Tag a subscriber, then remove the tag again later with the same Tag ID and email:

{
  "type": "convertkit",
  "parameters": {
    "resource": "tagSubscriber",
    "operation": "add",
    "tagId": "345678",
    "email": "{{ $json.email }}",
    "additionalFields": {
      "firstName": "{{ $json.firstName }}"
    }
  }
}

Create the custom field a later subscription will populate:

{
  "type": "convertkit",
  "parameters": {
    "resource": "customField",
    "operation": "create",
    "label": "Company Size"
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Manages ConvertKit email marketing: custom fields CRUD, form/sequence subscriber management, tag creation and listing, and tag-subscriber associations.

Behavior notes

• Field ID, Form ID and Sequence ID are one parameter. All three are the same underlying field, written as id in a node configuration — which one you see depends on the resource, and only one is ever in play at a time. Tag ID is separate, and is written as tagId.
• Create custom fields before you use them. The Custom Fields entries on Add Subscriber set values on fields that already exist; a key that matches nothing is ignored by ConvertKit.
• Tag IDs, not tag names. The Tag IDs entry on a form or sequence subscription takes comma-separated numeric IDs; run Tag: Get Many once to look them up.
• Tag: Create accepts several names at once, separated by commas, and creates them in a single call.
• List operations fan out. Every form, sequence, tag, custom field or subscription returned becomes its own output item, so the node after a Get Many runs once per record.
• Subscriber State filters Get Subscriptions on forms and sequences; leave it unset to take ConvertKit’s default. Tag Subscriber: Get Many returns the tag’s subscriptions whether or not you set it.