Tags allow you to organize and segment your subscribers based on their interests, behaviors, or characteristics. They’re essential for targeted email campaigns and subscriber management.

​
List tags

Returns a list of tags for your account.

​
Endpoint

GET /v3/tags

​
Parameters

​
api_key
string
required
Your account API key
curl https://api.convertkit.com/v3/tags?api_key=<your_public_api_key>

​
Create a tag

Create one or multiple tags for your account.

​
Endpoint

POST /v3/tags

​
Parameters

​
api_key
string
required
Your API key
​
tag
object|array
required
A JSON object or an array of JSON objects that includes the tag name. Each object should contain:
  • name (required): The name of the tag
curl -X POST https://api.convertkit.com/v3/tags\
     -H 'Content-Type: application/json'\
     -d '{ "api_secret": "<your_secret_api_key>",
           "tag": {
             "name": "Example Tag"
           } }'

​
Tag a subscriber

Tags are handled as subscriptions. Subscribe an email address to a tag to have that tag applied to the subscriber with that email address.

​
Endpoint

POST /v3/tags/#{tag_id}/subscribe

​
Parameters

​
api_secret
string
required
Your API secret key
​
tag_id
integer
required
The ID of the tag you want to apply
​
email
string
required
Subscriber email address
​
first_name
string
Subscriber first name
​
fields
object
Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.
​
tags
array
Array of tag ids to subscribe to

​
Deprecated Parameters

​
courses
array
Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly.
​
forms
array
Array of form ids to subscribe to. You should add the subscriber to the form directly.
​
name
string
Subscriber first name. You should prefer using first_name listed above.
curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/subscribe\
     -H "Content-Type: application/json; charset=utf-8"\
     -d '{ 
            "api_secret": "<your_secret_api_key>",
            "email": "[email protected]"
         }'

​
Remove tag from a subscriber

Remove a specific tag from a subscriber by subscriber ID.

​
Endpoint

DELETE /v3/subscribers/#{subscriber_id}/tags/#{tag_id}

​
Parameters

​
api_secret
string
required
Your API secret key
​
subscriber_id
integer
required
The ID of the subscriber
​
tag_id
integer
required
The ID of the tag to remove
curl -X DELETE https://api.convertkit.com/v3/subscribers/<subscriber_id>/tags/<tag_id>?api_secret=<your_secret_api_key>

​
Remove tag from a subscriber by email

Remove a specific tag from a subscriber by email address.

​
Endpoint

POST /v3/tags/#{tag_id}/unsubscribe

​
Parameters

​
api_secret
string
required
Your API secret key
​
tag_id
integer
required
The ID of the tag to remove
​
email
string
required
Subscriber email address
curl -X POST https://api.convertkit.com/v3/tags/<tag_id>/unsubscribe\
    -H "Content-Type: application/json; charset=utf-8"\
    -d '{ 
          "api_secret": "<your_secret_api_key>",
          "email": "[email protected]"
        }'

​
List subscriptions to a tag

List subscriptions to a tag including subscriber data.

​
Endpoint

GET /v3/tags/#{tag_id}/subscriptions

​
Parameters

​
api_secret
string
required
Your API secret key
​
tag_id
integer
required
The ID of the tag you want to retrieve subscriptions for
​
sort_order
string
Sort order for results (asc or desc). asc to list subscribers added oldest to newest, desc to list subscribers added newest to oldest. Default is asc.
​
subscriber_state
string
Filter by subscriber state (active or cancelled). Receive only active subscribers or cancelled subscribers.
​
page
string
The page of results being requested. Default value is 1. Each page of results will contain up to 50 subscriptions.
curl https://api.convertkit.com/v3/tags/<tag_id>/subscriptions?api_secret=<your_secret_api_key>