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>