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.
Returns a list of tags for your account.
Endpoint GET /v3/tagsParameters curl https://api.convertkit.com/v3/tags?api_key= < your_public_api_ke y >
{ "tags" : [ { "id" : 1 , "name" : "House Stark" , "created_at" : "2016-02-28T08:07:00Z" }, { "id" : 2 , "name" : "House Lannister" , "created_at" : "2016-02-28T08:07:00Z" } ] }
Create a tag Create one or multiple tags for your account.
Endpoint POST /v3/tagsParameters 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 Request (Single Tag)
Request (Multiple Tags)
Response (Single Tag)
Response (Multiple Tags)
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" } }'
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" }, { "name": "Example Tag 2" }] }'
{ "account_id" : 1 , "created_at" : "2017-04-12T11:10:32Z" , "deleted_at" : null , "id" : 1 , "name" : "Example Tag" , "state" : "available" , "updated_at" : "2017-04-12T11:10:32Z" }
[{ "account_id" : 1 , "created_at" : "2017-04-12T11:10:32Z" , "deleted_at" : null , "id" : 1 , "name" : "Example Tag" , "state" : "available" , "updated_at" : "2017-04-12T11:10:32Z" }, { "account_id" : 1 , "created_at" : "2017-04-12T11:11:566Z" , "deleted_at" : null , "id" : 2 , "name" : "Example Tag 2" , "state" : "available" , "updated_at" : "2017-04-12T11:11:566Z" }]
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}/subscribeParameters The ID of the tag you want to apply
Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.
Array of tag ids to subscribe to
Deprecated Parameters Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly.
Array of form ids to subscribe to. You should add the subscriber to the form directly.
Subscriber first name. You should prefer using first_name listed above.
curl -X POST https://api.convertkit.com/v3/tags/ < tag_i d > /subscribe \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "api_secret": "<your_secret_api_key>", "email": "jonsnow@example.com" }'
{ "subscription" : { "id" : 3 , "state" : "inactive" , "created_at" : "2016-02-28T08:07:00Z" , "source" : null , "referrer" : null , "subscribable_id" : 1 , "subscribable_type" : "tag" , "subscriber" : { "id" : 1 } } }
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 The ID of the tag to remove
curl -X DELETE https://api.convertkit.com/v3/subscribers/ < subscriber_i d > /tags/ < tag_i d > ?api_secret= < your_secret_api_ke y >
{ "id" : 1 , "name" : "House Stark" , "created_at" : "2016-02-28T08:07:00Z" }
Remove tag from a subscriber by email Remove a specific tag from a subscriber by email address.
Endpoint POST /v3/tags/#{tag_id}/unsubscribeParameters The ID of the tag to remove
curl -X POST https://api.convertkit.com/v3/tags/ < tag_i d > /unsubscribe \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "api_secret": "<your_secret_api_key>", "email": "jonsnow@example.com" }'
{ "id" : 1 , "name" : "House Stark" , "created_at" : "2016-02-28T08:07:00Z" }
List subscriptions to a tag List subscriptions to a tag including subscriber data.
Endpoint GET /v3/tags/#{tag_id}/subscriptionsParameters The ID of the tag you want to retrieve subscriptions for
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.
Filter by subscriber state (active or cancelled). Receive only active subscribers or cancelled subscribers.
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_i d > /subscriptions?api_secret= < your_secret_api_ke y >
{ "total_subscriptions" : 2 , "page" : 1 , "total_pages" : 1 , "subscriptions" : [ { "id" : 1 , "state" : "active" , "created_at" : "2016-02-28T08:07:00Z" , "source" : null , "referrer" : null , "subscribable_id" : 1 , "subscribable_type" : "tag" , "subscriber" : { "id" : 1 , "first_name" : "Jon" , "email_address" : "jonsnow@example.com" , "state" : "active" , "created_at" : "2016-02-28T08:07:00Z" , "fields" : { "last_name" : "Snow" } } }, { "id" : 2 , "state" : "active" , "created_at" : "2016-02-27T08:07:00Z" , "source" : null , "referrer" : null , "subscribable_id" : 1 , "subscribable_type" : "tag" , "subscriber" : { "id" : 2 , "first_name" : "Arya" , "email_address" : "arya@example.com" , "state" : "active" , "created_at" : "2016-02-27T08:07:00Z" , "fields" : { "last_name" : "Stark" } } } ] }
