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 provides operations to manage resources such as Custom Fields, Forms, Sequences, Subscribers, Subscriptions, and Tags within your ConvertKit account.

Operation Details

Add a Subscriber to Form

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

Input Parameters:

• FormId: The unique identifier of the form to add subscriber to. Must be a positive integer.
• EmailAddress: The email address of the subscriber to add.

Options:

• FirstName: The first name of the subscriber (optional).
• Fields: Custom field values as a JSON string. Example: {"field_key": "value"}

Output:

• SubscriberId (number): The unique identifier of the newly added subscriber.
• EmailAddress (string): The email address of the subscriber.
• FirstName (string): The first name of the subscriber.
• CreatedAt (string): The timestamp when the subscriber account was created.
• AddedAt (string): The timestamp when the subscriber was added to the form.
• StatusCode (number): Operation status code: 201 (created), 400, 401, 403, 404, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Add a Subscriber to Sequence

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

Input Parameters:

• SequenceId: The unique identifier of the sequence to add subscriber to. Must be a positive integer.
• SubscriberId: The unique identifier of the subscriber to add. Must be a positive integer.

Output:

• SubscriberId (number): The unique identifier of the subscriber.
• EmailAddress (string): The email address of the subscriber.
• CreatedAt (string): The timestamp when the subscription was created.
• StatusCode (number): Operation status code: 201 (created), 400, 401, 403, 404, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Add a Tag to Subscriber

Adds a tag to a subscriber in ConvertKit.

Input Parameters:

• SubscriberId: The ID of the subscriber to add the tag to.
• TagId: The ID of the tag to add.

Output:

• TagId (number): The unique identifier of the tag that was added.
• Name (string): The name of the tag.
• StatusCode (number): Operation status code: 200 (success), 400, 401, 403, 404, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Create a Custom Field

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

Input Parameters:

• Label: The display label for the custom field. This is what subscribers and admins will see in the ConvertKit interface.
• KeyName: The unique identifier for the custom field used in API calls and integrations. Use lowercase letters, numbers, and underscores only.

Output:

• FieldId (number): The unique identifier of the newly created custom field.
• Label (string): The display label of the custom field.
• KeyName (string): The unique key name of the custom field.
• CreatedAt (string): The timestamp when the custom field was created in ISO 8601 format.
• StatusCode (number): Operation status code: 201 (created successfully), 401 (authentication error), 422 (validation error), 500 (server error), -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Create a Tag

Creates a new tag in ConvertKit.

Input Parameters:

• Name: The name of the tag to create.

Output:

• TagId (number): The unique identifier of the newly created tag.
• Name (string): The name of the tag.
• CreatedAt (string): The timestamp when the tag was created in ISO 8601 format.
• StatusCode (number): Operation status code: 201 (success), 400, 401, 403, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Delete a Custom Field

Deletes a custom field in ConvertKit by its field ID. This action cannot be undone.

Input Parameters:

• FieldId: The unique identifier of the custom field to delete. Must be a positive integer.

Output:

• FieldId (number): The unique identifier of the deleted custom field.
• Deleted (bool): Indicates whether the field was successfully deleted.
• StatusCode (number): Operation status code: 204 (deleted successfully), 401 (authentication error), 404 (not found), 500 (server error), -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Delete a Tag from a Subscriber

Deletes a tag from a subscriber in ConvertKit.

Input Parameters:

• SubscriberId: The ID of the subscriber.
• TagId: The ID of the tag to delete.

Output:

• SubscriberId (number): The unique identifier of the subscriber.
• TagId (number): The unique identifier of the tag that was deleted.
• Deleted (bool): Whether the tag was successfully deleted from the subscriber.
• StatusCode (number): Operation status code: 204 (success), 400, 401, 403, 404, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Get all Subscriptions to Form

Retrieves a list of all subscriptions to a form including subscriber data with pagination support.

Input Parameters:

• FormId: The unique identifier of the form to get subscriptions for. Must be a positive integer.

Options:

• PerPage: Number of subscriptions to return per page. Default is 500, maximum is 1000.
• After: Pagination cursor for retrieving the next page of results.
• Before: Pagination cursor for retrieving the previous page of results.

Output:

• Subscriptions (object-array): Array of subscription objects with subscriber details.
• Pagination (object): Pagination information containing HasPreviousPage, HasNextPage, StartCursor, EndCursor, and PerPage.
• StatusCode (number): Operation status code: 200 (success), 400, 401, 403, 404, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Get all Subscriptions to a Sequence

Retrieves a list of all subscriptions to a sequence including subscriber data with pagination support.

Input Parameters:

• SequenceId: The unique identifier of the sequence to get subscriptions for. Must be a positive integer.

Options:

• PerPage: Number of subscriptions to return per page. Default is 500, maximum is 1000.
• After: Pagination cursor for retrieving the next page of results.
• Before: Pagination cursor for retrieving the previous page of results.

Output:

• Subscriptions (object-array): Array of subscription objects with subscriber details.
• Pagination (object): Pagination information containing HasPreviousPage, HasNextPage, StartCursor, EndCursor, and PerPage.
• StatusCode (number): Operation status code: 200 (success), 400, 401, 403, 404, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Get many Custom Fields

Retrieves a list of all custom fields in ConvertKit with pagination support.

Options:

• PerPage: Number of custom fields to return per page. Default is 500, maximum is 1000.
• After: Pagination cursor for retrieving the next page of results. Use the EndCursor value from the previous response.
• Before: Pagination cursor for retrieving the previous page of results. Use the StartCursor value from the previous response.

Output:

• CustomFields (object-array): Array of custom field objects containing FieldId, Label, KeyName, and CreatedAt.
• Pagination (object): Pagination information containing HasPreviousPage, HasNextPage, StartCursor, EndCursor, and PerPage.
• StatusCode (number): Operation status code: 200 (success), 401 (authentication error), 422 (validation error), 500 (server error), -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Get many Forms

Retrieves a list of all forms in ConvertKit with pagination support.

Options:

• PerPage: Number of forms to return per page. Default is 500, maximum is 1000.
• After: Pagination cursor for retrieving the next page of results.
• Before: Pagination cursor for retrieving the previous page of results.

Output:

• Forms (object-array): Array of form objects containing FormId, Name, and CreatedAt.
• Pagination (object): Pagination information containing HasPreviousPage, HasNextPage, StartCursor, EndCursor, and PerPage.
• StatusCode (number): Operation status code: 200 (success), 400, 401, 403, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Get many Sequences

Retrieves a list of all sequences (automations) in ConvertKit with pagination support.

Options:

• PerPage: Number of sequences to return per page. Default is 500, maximum is 1000.
• After: Pagination cursor for retrieving the next page of results.
• Before: Pagination cursor for retrieving the previous page of results.

Output:

• Sequences (object-array): Array of sequence objects containing SequenceId, Name, Hold, Repeat, and CreatedAt.
• Pagination (object): Pagination information containing HasPreviousPage, HasNextPage, StartCursor, EndCursor, and PerPage.
• StatusCode (number): Operation status code: 200 (success), 400, 401, 403, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Get many Tag Subscriptions

Retrieves a list of all subscriptions to a tag in ConvertKit with pagination support.

Input Parameters:

• TagId: The ID of the tag.

Options:

• PerPage: Number of subscriptions to return per page. Default is 500, maximum is 1000.
• After: Pagination cursor for retrieving the next page of results.
• Before: Pagination cursor for retrieving the previous page of results.

Output:

• Subscriptions (object-array): Array of subscription objects with subscriber and tag details.
• Pagination (object): Pagination information containing HasPreviousPage, HasNextPage, StartCursor, EndCursor, and PerPage.
• StatusCode (number): Operation status code: 200 (success), 400, 401, 403, 404, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Get many Tags

Retrieves a list of all tags in ConvertKit with pagination support.

Options:

• PerPage: Number of tags to return per page. Default is 500, maximum is 1000.
• After: Pagination cursor for retrieving the next page of results.
• Before: Pagination cursor for retrieving the previous page of results.

Output:

• Tags (object-array): Array of tag objects with tag details.
• Pagination (object): Pagination information containing HasPreviousPage, HasNextPage, StartCursor, EndCursor, and PerPage.
• StatusCode (number): Operation status code: 200 (success), 400, 401, 403, 422, 500, -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

Update a Custom Field

Updates an existing custom field in ConvertKit with new label and/or key name.

Input Parameters:

• FieldId: The unique identifier of the custom field to update. Must be a positive integer.

Options:

• Label: New display label for the custom field. Leave empty to keep the existing label.
• KeyName: New unique identifier for the custom field used in API calls. Leave empty to keep the existing key name.

Output:

• FieldId (number): The unique identifier of the updated custom field.
• Label (string): The updated display label of the custom field.
• KeyName (string): The updated unique key name of the custom field.
• CreatedAt (string): The timestamp when the custom field was originally created in ISO 8601 format.
• StatusCode (number): Operation status code: 200 (updated successfully), 400 (bad request), 401 (authentication error), 403 (forbidden), 404 (not found), 422 (validation error), 500 (server error), -1 (parameter error).
• ErrorMessage (string): Error description if the operation fails, empty string on success.

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.