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

# Subscribers

> Subscribers v3 endpoints

Subscribers are the core of your email marketing. These endpoints allow you to manage your subscriber list, update their information, and track their engagement with your content.

## List subscribers

Returns a list of your subscribers with filtering and search capabilities.

### Endpoint

`GET /v3/subscribers`

### Parameters

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

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

<ParamField path="from" type="string">
  Filter subscribers added on or after this date (format `yyyy-mm-dd`)
</ParamField>

<ParamField path="to" type="string">
  Filter subscribers added on or before this date (format `yyyy-mm-dd`)
</ParamField>

<ParamField path="updated_from" type="string">
  Filter subscribers who have been updated after this date (format `yyyy-mm-dd`)
</ParamField>

<ParamField path="updated_to" type="string">
  Filter subscribers who have been updated before this date (format `yyyy-mm-dd`)
</ParamField>

<ParamField path="sort_order" type="string">
  Sort order for results (`asc` or `desc`)
</ParamField>

<ParamField path="sort_field" type="string">
  Field to sort by. Supports `cancelled_at` only.
</ParamField>

<ParamField path="email_address" type="string">
  Search subscribers by email address
</ParamField>

<CodeGroup>
  ```shell Request theme={null}
  curl https://api.convertkit.com/v3/subscribers?api_secret=<your_secret_api_key>&from=2016-02-01&to=2015-02-28
  ```

  ```json Response theme={null}
  {
    "total_subscribers": 3,
    "page": 1,
    "total_pages": 1,
    "subscribers": [
      {
        "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,
        "first_name": "Arya",
        "email_address": "aryastark@example.com",
        "state": "active",
        "created_at": "2016-02-28T08:07:00Z",
        "fields": {
          "last_name": "Stark"
        }
      }
    ]
  }
  ```
</CodeGroup>

## View a single subscriber

Returns data for a single subscriber.

### Endpoint

`GET /v3/subscribers/#{subscriber_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 you want to retrieve
</ParamField>

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

  ```json Response theme={null}
  {
    "subscriber": {
      "id": 1,
      "first_name": "Jon",
      "email_address": "jonsnow@example.com",
      "state": "active",
      "created_at": "2016-02-28T08:07:00Z",
      "fields": {
        "last_name": "Snow"
      }
    }
  }
  ```
</CodeGroup>

Subscribers are the core of your email marketing. These endpoints allow you to manage your subscriber list, update their information, and track their engagement with your content.

## Update subscriber

Updates the information for a single subscriber.

**NOTE**: *The API response returned when updating custom fields is dependent on the number of custom fields in the request. **A maximum of 140 custom fields are allowed.** Requests that exceed this limit will return a response of* `400`.

### Endpoint

`PUT /v3/subscribers/#{subscriber_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 you want to update
</ParamField>

<ParamField path="first_name" type="string">
  Updated first name for the subscriber
</ParamField>

<ParamField path="email_address" type="string">
  Updated email address for the subscriber
</ParamField>

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

<CodeGroup>
  ```shell Request theme={null}
  curl -X PUT https://api.convertkit.com/v3/subscribers/<subscriber_id>\
       -H 'Content-Type: application/json'\
       -d '{ "api_secret": "<your_secret_api_key>",
             "first_name": "Jon",
             "email_address": "jonsnow@example.com",
             "fields": {
               "last_name": "Snow"
             } }'
  ```

  ```json Response (Up to 10 custom fields, status 200) theme={null}
  {
    "subscriber": {
      "id": 1,
      "first_name": "Jon",
      "email_address": "jonsnow@example.com",
      "state": "active",
      "created_at": "2016-02-28T08:07:00Z",
      "fields": {
        "last_name": "Snow"
      }
    }
  }
  ```

  ```json Response (11 to 140 custom fields, status 202) theme={null}
  {
    "subscriber": {
      "id": 1,
      "first_name": "Jon",
      "email_address": "jonsnow@example.com",
      "state": "active",
      "created_at": "2016-02-28T08:07:00Z",
      "fields": {
        "last_name": "Snow"
      }
    }
  }
  ```
</CodeGroup>

## Unsubscribe subscriber

Unsubscribe an email address from all your forms and sequences.

### Endpoint

`PUT /v3/unsubscribe`

### Parameters

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

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

<CodeGroup>
  ```shell Request theme={null}
  curl -X PUT https://api.convertkit.com/v3/unsubscribe\
       -H 'Content-Type: application/json'\
       -d '{ "api_secret": "<your_secret_api_key>",
             "email": "jonsnow@example.com" }'
  ```

  ```json Response theme={null}
  {
    "subscriber": {
      "id": 1,
      "first_name": "Jon",
      "email_address": "jonsnow@example.com",
      "state": "active",
      "created_at": "2016-02-28T08:07:00Z",
      "fields": {
        "last_name": "Snow"
      }
    }
  }
  ```
</CodeGroup>

## List tags for a subscriber

Lists all the tags for a subscriber.

### Endpoint

`GET /v3/subscribers/#{subscriber_id}/tags`

### Parameters

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

<ParamField path="subscriber_id" type="string" required={true}>
  The ID of the subscriber whose tags you want to retrieve
</ParamField>

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

  ```json Response theme={null}
  {
    "tags": [
      {
        "id": 1,
        "name": "Email Newsletter",
        "created_at": "2016-06-09T17:54:22Z"
      }
    ]
  }
  ```
</CodeGroup>