Skip to main content
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

​
api_secret
string
required
Your API secret key
​
page
integer
The page of results being requested. Default value is 1. Each page of results will contain up to 50 subscribers.
​
from
string
Filter subscribers added on or after this date (format yyyy-mm-dd)
​
to
string
Filter subscribers added on or before this date (format yyyy-mm-dd)
​
updated_from
string
Filter subscribers who have been updated after this date (format yyyy-mm-dd)
​
updated_to
string
Filter subscribers who have been updated before this date (format yyyy-mm-dd)
​
sort_order
string
Sort order for results (asc or desc)
​
sort_field
string
Field to sort by. Supports cancelled_at only.
​
email_address
string
Search subscribers by email address
curl https://api.convertkit.com/v3/subscribers?api_secret=<your_secret_api_key>&from=2016-02-01&to=2015-02-28

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

​
View a single subscriber

Returns data for a single subscriber.

​
Endpoint

GET /v3/subscribers/#{subscriber_id}

​
Parameters

​
api_secret
string
required
Your API secret key
​
subscriber_id
integer
required
The ID of the subscriber you want to retrieve
curl https://api.convertkit.com/v3/subscribers/<subscriber_id>?api_secret=<your_secret_api_key>

{
  "subscriber": {
    "id": 1,
    "first_name": "Jon",
    "email_address": "jonsnow@example.com",
    "state": "active",
    "created_at": "2016-02-28T08:07:00Z",
    "fields": {
      "last_name": "Snow"
    }
  }
}
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

​
api_secret
string
required
Your API secret key
​
subscriber_id
integer
required
The ID of the subscriber you want to update
​
first_name
string
Updated first name for the subscriber
​
email_address
string
Updated email address for the subscriber
​
fields
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.
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"
           } }'

{
  "subscriber": {
    "id": 1,
    "first_name": "Jon",
    "email_address": "jonsnow@example.com",
    "state": "active",
    "created_at": "2016-02-28T08:07:00Z",
    "fields": {
      "last_name": "Snow"
    }
  }
}

{
  "subscriber": {
    "id": 1,
    "first_name": "Jon",
    "email_address": "jonsnow@example.com",
    "state": "active",
    "created_at": "2016-02-28T08:07:00Z",
    "fields": {
      "last_name": "Snow"
    }
  }
}

​
Unsubscribe subscriber

Unsubscribe an email address from all your forms and sequences.

​
Endpoint

PUT /v3/unsubscribe

​
Parameters

​
api_secret
string
required
Your API secret key
​
email
string
required
Subscriber email address
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" }'

{
  "subscriber": {
    "id": 1,
    "first_name": "Jon",
    "email_address": "jonsnow@example.com",
    "state": "active",
    "created_at": "2016-02-28T08:07:00Z",
    "fields": {
      "last_name": "Snow"
    }
  }
}

​
List tags for a subscriber

Lists all the tags for a subscriber.

​
Endpoint

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

​
Parameters

​
api_key
string
required
Your account API key
​
subscriber_id
string
required
The ID of the subscriber whose tags you want to retrieve
curl https://api.convertkit.com/v3/subscribers/<subscriber_id>/tags?api_key=<your_public_api_key>

{
  "tags": [
    {
      "id": 1,
      "name": "Email Newsletter",
      "created_at": "2016-06-09T17:54:22Z"
    }
  ]
}