ConvertKit

1. Overview

ConvertKit is a powerful email marketing platform designed for online creators, including bloggers, podcasters, and YouTubers. It helps users grow their audience, foster communities, and earn a living online through tools like email automation, landing pages, and forms.

The GoInsight Convertkit node allows you to seamlessly integrate your email marketing operations into your automated workflows. You can manage the core components of your ConvertKit account, including:

• Subscriber Management: Add subscribers to forms, sequences, and apply or remove tags.
• Audience Segmentation: Create and manage tags to organize your audience effectively.
• Data Management: Create, update, and delete custom fields to store additional information about your subscribers.
• Resource Retrieval: Fetch lists of your forms, sequences, tags, custom fields, and subscriptions.

2. Prerequisites

Before using this node, you must have a valid Convertkit account. You may also need appropriate permissions within your Convertkit account to access or generate API credentials.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node allows you to manage various resources within ConvertKit, including Custom Fields, Forms, Sequences, and Tags.

Operation Details

Create a Custom Field

Creates a new custom field in ConvertKit to store additional subscriber information.

⚠️ Important:

The KeyName (internal identifier) is automatically generated by the API from the Label as a lowercase, underscored version (e.g., "Company Name" → "company_name"). You cannot manually specify the KeyName.

✅ Idempotent Behavior:

If a custom field with the same Label already exists, this action will return the existing field instead of creating a duplicate. This makes it safe to retry on network timeouts.

Input Parameters:

• Label: The display label for the custom field. This is what subscribers and admins will see in the ConvertKit interface. ⚠️ KeyName Auto-Generation: The KeyName (internal identifier) is automatically generated by ConvertKit API from this Label as a lowercase, underscored version (e.g., "Company Name" → "company_name"). You cannot manually specify the KeyName - it's always derived from the Label. Duplicate Labels are not allowed. Example: "Company Name", "Job Title", "Phone Number"

Output:

• CustomField (object): The custom field object containing all field information. Structure: {"id": number, "label": string, "key_name": string, "created_at": string (ISO 8601)}
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete a Custom Field

⚠️ WARNING: This action permanently deletes a custom field in ConvertKit by its field ID.

This operation cannot be undone. All subscriber data associated with this field will be lost.

Use with extreme caution.

Input Parameters:

• FieldId: The unique identifier of the custom field to delete. Must be a positive integer. How to get FieldId: You can obtain it by calling Get Many Custom Fields action. ⚠️ WARNING: Deleting a custom field is permanent and cannot be undone. All subscriber data associated with this field will be lost. Example: 123456

Output:

• DeletionResult (object): The deletion result object containing field ID and deletion status. Structure: {"field_id": number, "deleted": boolean}
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get many Custom Fields

Retrieves a list of all custom fields in ConvertKit with pagination support. Use the pagination object within the result to navigate through multiple pages of results. Custom fields are used to store additional subscriber information beyond the default fields (email, name, etc.).

Input Parameters:

• PerPage: Number of custom fields to return per page. Default is 500, maximum is 1000. Use smaller values for faster responses, larger values to reduce API calls when fetching many fields.
• After: Pagination cursor for retrieving the next page of results. Use the end_cursor value from the previous response's pagination object. Leave empty for the first page.
• Before: Pagination cursor for retrieving the previous page of results. Use the start_cursor value from the current response's pagination object. Leave empty for forward pagination.

Output:

• CustomFieldsResult (object): The custom fields result object containing the list of custom fields and pagination information. Structure: {"custom_fields": array, "pagination": object}. Each custom field contains: field_id (number), label (string), key_name (string), and created_at (string). The pagination object contains: has_previous_page (boolean), has_next_page (boolean), start_cursor (string), end_cursor (string), and per_page (number).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Update a Custom Field

Updates the label of an existing custom field in ConvertKit.

⚠️ IMPORTANT:

Only the Label can be updated. KeyName cannot be changed after creation (ConvertKit API limitation). To change a field's key_name, you must delete the old field and create a new one.

Input Parameters:

• FieldId: The unique identifier of the custom field to update. Must be a positive integer. How to get FieldId: You can obtain field IDs by calling the Get Many Custom Fields action. Example: 12345678
• Label: New display label for the custom field (shown to subscribers in forms). This is the only field that can be updated. Example: "Customer Industry"

Output:

• CustomField (object): The updated custom field object containing field_id (number), label (string), key_name (string), and created_at (string - ISO 8601 timestamp). All fields reflect the current state after the update.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Add a Subscriber to Form

Adds a new subscriber to a form in ConvertKit with email address and optional first name and custom fields.

Idempotency:

ConvertKit automatically handles duplicate email addresses - if the subscriber already exists, it will be updated instead of creating a duplicate.

Input Parameters:

• FormId: The unique identifier of the form to add subscriber to. Must be a positive integer. How to get FormId: You can find it in the ConvertKit dashboard by viewing the form URL (e.g., https://app.convertkit.com/forms/5678901), or call the List Forms API to retrieve all available forms. Example: 5678901
• EmailAddress: The email address of the subscriber to add. This is the primary identifier for the subscriber. Format: user@example.com
• FirstName: The first name of the subscriber (optional). Used for personalization in email campaigns.
• Fields: Custom field values as key-value pairs. Common fields: - phone: Contact phone number - company: Company name - website: Company website URL - job_title: Job title - location: Geographic location For a complete list of available custom fields, check your ConvertKit account settings or API documentation. Example: {"phone": "+1-555-0100", "company": "Acme Corp", "website": "https://acme.com"}

Output:

• Subscriber (object): The subscriber object containing all subscriber information. Structure: {"id": number, "email_address": string, "first_name": string, "created_at": string (ISO 8601), "added_at": string (ISO 8601), "fields": object}
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get all Subscriptions to Form

Retrieves a list of all subscriptions to a form including subscriber data with pagination support. Use the pagination object within the result to navigate through multiple pages of results. Each subscription includes full subscriber information such as email, name, custom fields, and referrer data.

Input Parameters:

• FormId: The unique identifier of the form to get subscriptions for. Must be a positive integer. How to get FormId: You can find it in the ConvertKit dashboard by viewing the form URL (e.g., https://app.convertkit.com/forms/5678901), or call the Get Many Forms action to retrieve all available forms. Example: 5678901
• PerPage: Number of subscriptions to return per page. Default is 500, maximum is 1000. Use smaller values for faster responses, larger values to reduce API calls when fetching many subscriptions.
• After: Pagination cursor for retrieving the next page of results. Use the end_cursor value from the previous response's pagination object. Leave empty for the first page.
• Before: Pagination cursor for retrieving the previous page of results. Use the start_cursor value from the current response's pagination object. Leave empty for forward pagination.

Output:

• SubscriptionsResult (object): The subscriptions result object containing the list of subscriptions and pagination information. Structure: {"subscriptions": array, "pagination": object}. Each subscription contains: subscriber_id (number), form_id (number), added_at (string), and a subscriber object. The pagination object contains: has_previous_page (boolean), has_next_page (boolean), start_cursor (string), end_cursor (string), and per_page (number).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get many Forms

Retrieves a list of all forms in ConvertKit with pagination support. Use the pagination object within the result to navigate through multiple pages of results. Forms are used to collect subscriber information and grow your email list.

Input Parameters:

• PerPage: Number of forms to return per page. Default is 500, maximum is 1000. Use smaller values for faster responses, larger values to reduce API calls when fetching many forms.
• After: Pagination cursor for retrieving the next page of results. Use the end_cursor value from the previous response's pagination object. Leave empty for the first page.
• Before: Pagination cursor for retrieving the previous page of results. Use the start_cursor value from the current response's pagination object. Leave empty for forward pagination.

Output:

• FormsResult (object): The forms result object containing the list of forms and pagination information. Structure: {"forms": array, "pagination": object}. Each form contains: form_id (number), name (string), and created_at (string). The pagination object contains: has_previous_page (boolean), has_next_page (boolean), start_cursor (string), end_cursor (string), and per_page (number).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Add a Subscriber to Sequence

Adds a subscriber to a sequence (automation) in ConvertKit.

Idempotency:

If the subscriber is already in the sequence, this operation is idempotent and will not create duplicates or return an error.

Input Parameters:

• SequenceId: The unique identifier of the sequence to add subscriber to. Must be a positive integer. How to get SequenceId: You can find it in the ConvertKit dashboard (Grow → Sequences → click on a sequence, the ID is in the URL like https://app.convertkit.com/sequences/1234567), or call the Get Many Sequences API to retrieve all available sequences. Example: 1234567
• SubscriberId: The unique identifier of the subscriber to add. Must be a positive integer. How to get SubscriberId: You can obtain it by calling Create a Subscriber, Search Subscribers, or Get Many Subscribers actions. The subscriber must already exist in your ConvertKit account. Example: 9876543

Output:

• Subscription (object): The subscription object containing all subscription information. Structure: {"subscriber_id": number, "email_address": string, "created_at": string (ISO 8601), "sequence_id": number}
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get all Subscriptions to a Sequence

Retrieves a list of all subscriptions to a sequence including subscriber data with pagination support. Use the pagination object within the result to navigate through multiple pages of results. Each subscription includes full subscriber information such as email, name, custom fields, and state.

Input Parameters:

• SequenceId: The unique identifier of the sequence to get subscriptions for. Must be a positive integer. How to get SequenceId: You can find it in the ConvertKit dashboard by viewing the sequence URL, or call the Get Many Sequences action to retrieve all available sequences. Example: 123456
• PerPage: Number of subscriptions to return per page. Default is 500, maximum is 1000. Use smaller values for faster responses, larger values to reduce API calls when fetching many subscriptions.
• After: Pagination cursor for retrieving the next page of results. Use the end_cursor value from the previous response's pagination object. Leave empty for the first page.
• Before: Pagination cursor for retrieving the previous page of results. Use the start_cursor value from the current response's pagination object. Leave empty for forward pagination.

Output:

• SubscriptionsResult (object): The subscriptions result object containing the list of subscriptions and pagination information. Structure: {"subscriptions": array, "pagination": object}. Each subscription contains: subscriber_id (number), sequence_id (number), added_at (string), and a subscriber object. The pagination object contains: has_previous_page (boolean), has_next_page (boolean), start_cursor (string), end_cursor (string), and per_page (number).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get many Sequences

Retrieves a list of all sequences (automations) in ConvertKit with pagination support. Use the pagination object within the result to navigate through multiple pages of results. Sequences are automated email series that send over time to nurture subscribers.

Input Parameters:

• PerPage: Number of sequences to return per page. Default is 500, maximum is 1000. Use smaller values for faster responses, larger values to reduce API calls when fetching many sequences.
• After: Pagination cursor for retrieving the next page of results. Use the end_cursor value from the previous response's pagination object. Leave empty for the first page.
• Before: Pagination cursor for retrieving the previous page of results. Use the start_cursor value from the current response's pagination object. Leave empty for forward pagination.

Output:

• SequencesResult (object): The sequences result object containing the list of sequences and pagination information. Structure: {"sequences": array, "pagination": object}. Each sequence contains: sequence_id (number), name (string), hold (boolean), repeat (boolean), and created_at (string). The pagination object contains: has_previous_page (boolean), has_next_page (boolean), start_cursor (string), end_cursor (string), and per_page (number).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Add a Tag to Subscriber

Adds a tag to a subscriber in ConvertKit.

Idempotency:

This operation is idempotent - adding the same tag multiple times will not cause an error or create duplicates.

Input Parameters:

• SubscriberId: The ID of the subscriber to add the tag to. Must be a positive integer. How to get SubscriberId: You can obtain it by calling Create a Subscriber, Search Subscribers, or Get Many Subscribers actions. The subscriber must already exist in your ConvertKit account. Example: 123456789
• TagId: The ID of the tag to add. Must be a positive integer. How to get TagId: You can obtain it by calling Get Many Tags or Create a Tag actions. The tag must already exist in your ConvertKit account. Example: 987654

Output:

• TagSubscription (object): The tag subscription object containing tag information. Structure: {"tag_id": number, "subscriber_id": number, "created_at": string (ISO 8601)}. Note: The tag name is not returned by this API endpoint.
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Create a Tag

Creates a new tag in ConvertKit. Tags are used to categorize and segment subscribers for targeted campaigns and automation workflows.

Note:

ConvertKit allows duplicate tag names - if a tag with the same name already exists, a new tag with a different ID will be created.

Input Parameters:

• Name: The name of the tag to create. Must be 1-255 characters. Tags are used to categorize and segment subscribers for targeted campaigns and automation workflows. Note: ConvertKit allows duplicate tag names - if a tag with the same name already exists, a new tag with a different ID will be created. Example: "VIP Customer", "Newsletter Subscriber", "Product Launch 2024"

Output:

• Tag (object): The tag object containing all tag information. Structure: {"id": number, "name": string, "created_at": string (ISO 8601)}
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Delete a Tag from a Subscriber

Removes a tag from a subscriber in ConvertKit. This operation is idempotent - removing a tag that is not associated with the subscriber will not cause an error.

Note:

This only removes the tag association, it does not delete the tag itself or the subscriber.

Input Parameters:

• SubscriberId: The ID of the subscriber to remove the tag from. Must be a positive integer. How to get SubscriberId: You can obtain it by calling Create a Subscriber, Search Subscribers, or Get Many Subscribers actions. Example: 123456789
• TagId: The ID of the tag to remove from the subscriber. Must be a positive integer. How to get TagId: You can obtain it by calling Get Many Tags or Create a Tag actions. Example: 987654

Output:

• TagRemovalResult (object): The tag removal result object containing subscriber ID, tag ID, and deletion status. Structure: {"subscriber_id": number, "tag_id": number, "deleted": boolean}
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get many Tag Subscriptions

Retrieves a list of all subscriptions to a tag in ConvertKit with pagination support. Use the pagination object within the result to navigate through multiple pages of results. Each subscription includes full subscriber information such as email, name, custom fields, and when they were tagged.

Input Parameters:

• TagId: The unique identifier of the tag to get subscriptions for. Must be a positive integer. How to get TagId: You can find it in the ConvertKit dashboard, or call the Get Many Tags action to retrieve all available tags. Example: 2744876
• PerPage: Number of subscriptions to return per page. Default is 500, maximum is 1000. Use smaller values for faster responses, larger values to reduce API calls when fetching many subscriptions.
• After: Pagination cursor for retrieving the next page of results. Use the end_cursor value from the previous response's pagination object. Leave empty for the first page.
• Before: Pagination cursor for retrieving the previous page of results. Use the start_cursor value from the current response's pagination object. Leave empty for forward pagination.

Output:

• SubscriptionsResult (object): The subscriptions result object containing the list of tag subscriptions and pagination information. Structure: {"subscriptions": array, "pagination": object}. Each subscription contains: subscriber_id (number), tag_id (number), tagged_at (string), and a subscriber object. The pagination object contains: has_previous_page (boolean), has_next_page (boolean), start_cursor (string), end_cursor (string), and per_page (number).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Get many Tags

Retrieves a list of all tags in ConvertKit with pagination support. Use the pagination object within the result to navigate through multiple pages of results. Tags are used to organize and segment subscribers for targeted email campaigns.

Input Parameters:

• PerPage: Number of tags to return per page. Default is 500, maximum is 1000. Use smaller values for faster responses, larger values to reduce API calls when fetching many tags.
• After: Pagination cursor for retrieving the next page of results. Use the end_cursor value from the previous response's pagination object. Leave empty for the first page.
• Before: Pagination cursor for retrieving the previous page of results. Use the start_cursor value from the current response's pagination object. Leave empty for forward pagination.

Output:

• TagsResult (object): The tags result object containing the list of tags and pagination information. Structure: {"tags": array, "pagination": object}. Each tag contains: tag_id (number), name (string), and created_at (string). The pagination object contains: has_previous_page (boolean), has_next_page (boolean), start_cursor (string), end_cursor (string), and per_page (number).
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API. Default value is 0. Use this for debugging and troubleshooting.
• StatusCode (number): Operation status code.
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow to add a new subscriber to a specific form in your ConvertKit account.

The workflow will consist of a Start node, a Convertkit tool node, and an Answer node.

1. Add the Tool Node:
   • In the workflow canvas, click the "+" button to add a new node.
   • In the panel that appears, select the "Tools" tab.
   • Find and select "Convertkit" from the list of tools.
   • From the list of supported operations for Convertkit, click on "Add a Subscriber to Form". This will add the node to your canvas.
2. Configure the Node:
   • Click on the newly added "Add a Subscriber to Form" node to open its configuration panel on the right.
   • Credentials: Find the credentials field at the top. Click the dropdown menu and select your pre-configured Convertkit credentials.
   • Parameters: Fill in the input parameters for the action.
   • FormId: Enter the numeric ID of the form you want to add the subscriber to. You can find this ID in the URL of the form's page in your ConvertKit dashboard (e.g., .../forms/123456/).
   • EmailAddress: Enter the email address of the new subscriber. You can hardcode a value for testing (e.g., test@example.com) or use a variable from a previous node, like {{start.email}}.
   • FirstName (Optional): You can provide the subscriber's first name, for instance, John.
   • Fields (Optional): If you have custom fields, you can populate them using a JSON string. For example, if you have a custom field with the key source, you could enter {"source": "GoInsight Workflow"}.
3. Run and Validate:
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
   • Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top-right to view the detailed inputs and outputs of the node, confirming that the operation was successful and retrieving the new SubscriberId.

After completing these steps, your workflow is fully configured. When run, it will add a new subscriber to the specified form in your ConvertKit account.

6. FAQs

Q: Why am I getting a 401 Unauthorized error?

A: This error typically indicates an issue with your API credentials. Please ensure that the API Secret you provided in the GoInsight credentials configuration is correct and has not expired or been revoked in your ConvertKit account settings.

Q: How do I find the ID for a Form, Sequence, or Tag?

A: You can usually find the ID in the URL of your ConvertKit dashboard when you are viewing the specific item.

• Form ID: Navigate to the form and look at the URL. It will be in the format .../forms/FORM_ID/....
• Sequence ID: Navigate to the sequence and check the URL for .../sequences/SEQUENCE_ID/....
• Tag ID: Go to the Subscribers page, click on a tag, and the URL will be .../tags/TAG_ID/subscribers.

Q: My "Add a Subscriber to Form" action is failing with a 422 Unprocessable Entity error. What could be the cause?

A: A 422 error usually means the data you sent was understood but could not be processed due to a validation error. Please check the following:

• Ensure the EmailAddress you are providing is in a valid format (e.g., name@domain.com).
• Verify that the FormId exists and is correct.
• If you are using the Fields parameter, make sure it is a valid JSON string.

7. Official Documentation

For more in-depth information about the ConvertKit API and its capabilities, please refer to the Convertkit Official API Documentation.