> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tags

> Tags v3 endpoints

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

<ParamField path="api_key" type="string" required={true}>
  Your account API key
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/tags?api_key=<your_public_api_key>
  ```

  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

## Create a tag

Create one or multiple tags for your account.

### Endpoint

`POST /v3/tags`

### Parameters

<ParamField path="api_key" type="string" required={true}>
  Your API key
</ParamField>

<ParamField path="tag" type="object|array" required={true}>
  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
</ParamField>

<CodeGroup>
  ```shell Request (Single Tag) theme={null}
  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"
             } }'
  ```

  ```shell Request (Multiple Tags) theme={null}
  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"
             }] }'
  ```

  ```json Response (Single Tag) theme={null}
  {
    "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"
  }
  ```

  ```json Response (Multiple Tags) theme={null}
  [{
    "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"
  }]
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="tag_id" type="integer" required={true}>
  The ID of the tag you want to apply
</ParamField>

<ParamField path="email" type="string" required={true}>
  Subscriber email address
</ParamField>

<ParamField path="first_name" type="string">
  Subscriber first name
</ParamField>

<ParamField path="fields" type="object">
  Object of key/value pairs for custom field(s). The custom field(s) must exist before you can use it here.
</ParamField>

<ParamField path="tags" type="array">
  Array of tag ids to subscribe to
</ParamField>

### Deprecated Parameters

<ParamField path="courses" type="array">
  Array of sequence ids to subscribe to. You should add the subscriber to the sequence directly.
</ParamField>

<ParamField path="forms" type="array">
  Array of form ids to subscribe to. You should add the subscriber to the form directly.
</ParamField>

<ParamField path="name" type="string">
  Subscriber first name. You should prefer using `first_name` listed above.
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  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"
           }'
  ```

  ```json Response theme={null}
  {
    "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
      }
    }
  }
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="subscriber_id" type="integer" required={true}>
  The ID of the subscriber
</ParamField>

<ParamField path="tag_id" type="integer" required={true}>
  The ID of the tag to remove
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl -X DELETE https://api.convertkit.com/v3/subscribers/<subscriber_id>/tags/<tag_id>?api_secret=<your_secret_api_key>
  ```

  ```json Response theme={null}
  {
    "id": 1,
    "name": "House Stark",
    "created_at": "2016-02-28T08:07:00Z"
  }
  ```
</CodeGroup>

## 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

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="tag_id" type="integer" required={true}>
  The ID of the tag to remove
</ParamField>

<ParamField path="email" type="string" required={true}>
  Subscriber email address
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  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"
          }'
  ```

  ```json Response theme={null}
  {
    "id": 1,
    "name": "House Stark",
    "created_at": "2016-02-28T08:07:00Z"
  }
  ```
</CodeGroup>

## List subscriptions to a tag

List subscriptions to a tag including subscriber data.

### Endpoint

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

### Parameters

<ParamField path="api_secret" type="string" required={true}>
  Your API secret key
</ParamField>

<ParamField path="tag_id" type="integer" required={true}>
  The ID of the tag you want to retrieve subscriptions for
</ParamField>

<ParamField path="sort_order" type="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`.
</ParamField>

<ParamField path="subscriber_state" type="string">
  Filter by subscriber state (`active` or `cancelled`). Receive only active subscribers or cancelled subscribers.
</ParamField>

<ParamField path="page" type="string">
  The page of results being requested. Default value is `1`. Each page of results will contain up to 50 subscriptions.
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/tags/<tag_id>/subscriptions?api_secret=<your_secret_api_key>
  ```

  ```json Response theme={null}
  {
    "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"
          }
        }
      }
    ]
  }
  ```
</CodeGroup>