Kit Developer Documentation

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/tags

Parameters

string

required

Your account API key

curl https://api.convertkit.com/v3/tags?api_key=<your_public_api_key>

{
  "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/tags

Parameters

string

required

Your API key

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"
           } }'

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}/subscribe

Parameters

string

required

Your API secret key

integer

required

The ID of the tag you want to apply

string

required

Subscriber email address

string

Subscriber first name

object

Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.

array

Array of tag ids to subscribe to

Deprecated Parameters

array

Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly.

array

Array of form ids to subscribe to. You should add the subscriber to the form directly.

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": "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

string

required

Your API secret key

integer

required

The ID of the subscriber

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>

{
  "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}/unsubscribe

Parameters

string

required

Your API secret key

integer

required

The ID of the tag to remove

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": "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}/subscriptions

Parameters

string

required

Your API secret key

integer

required

The ID of the tag you want to retrieve subscriptions for

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.

string

Filter by subscriber state (active or cancelled). Receive only active subscribers or cancelled subscribers.

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>

{
  "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"
        }
      }
    }
  ]
}

Getting Started

Endpoints

Tags

Endpoint

Parameters

Create a tag

Endpoint

Parameters

Tag a subscriber

Endpoint

Parameters

Deprecated Parameters

Remove tag from a subscriber

Endpoint

Parameters

Remove tag from a subscriber by email

Endpoint

Parameters

List subscriptions to a tag

Endpoint

Parameters

​List tags

​Endpoint

​Parameters

​Create a tag

​Endpoint

​Parameters

​Tag a subscriber

​Endpoint

​Parameters

​Deprecated Parameters

​Remove tag from a subscriber

​Endpoint

​Parameters

​Remove tag from a subscriber by email

​Endpoint

​Parameters

​List subscriptions to a tag

​Endpoint

​Parameters

List tags

Endpoint

Parameters

Create a tag

Endpoint

Parameters

Tag a subscriber

Endpoint

Parameters

Deprecated Parameters

Remove tag from a subscriber

Endpoint

Parameters

Remove tag from a subscriber by email

Endpoint

Parameters

List subscriptions to a tag

Endpoint

Parameters