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

​
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>
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": "[email protected]",
           "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": "[email protected]" }'

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