List subscribers

curl --request GET \
  --url https://api.kit.com/v4/subscribers \
  --header 'X-Kit-Api-Key: <api-key>'

require 'uri'
require 'net/http'

url = URI("https://api.kit.com/v4/subscribers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Kit-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

const options = {method: 'GET', headers: {'X-Kit-Api-Key': '<api-key>'}};

fetch('https://api.kit.com/v4/subscribers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.kit.com/v4/subscribers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Kit-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.kit.com/v4/subscribers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Kit-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://api.kit.com/v4/subscribers"

headers = {"X-Kit-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "subscribers": [
    {
      "id": 200,
      "state": "active",
      "first_name": "Alice",
      "email_address": "alice@convertkit.dev",
      "created_at": "2023-01-27T11:43:55Z",
      "fields": {
        "category": "One"
      },
      "attribution": {
        "referrer": "https://t.co/abc123",
        "utm_source": "twitter",
        "utm_medium": "cpc",
        "utm_campaign": "spring_launch",
        "utm_term": "newsletter+for+creators",
        "utm_content": "hero_cta",
        "source_type": "form_subscription",
        "source_name": "Welcome Form",
        "source_mechanism": "landing_page",
        "source_mechanism_id": null
      },
      "tags": [
        {
          "id": 1,
          "name": "VIP"
        }
      ],
      "location": {
        "city": "Portland",
        "state": "OR",
        "country": "US",
        "latitude": 45.5,
        "longitude": -122.6,
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "id": 201,
      "state": "active",
      "first_name": "Benito",
      "email_address": "benito@convertkit.dev",
      "created_at": "2023-02-03T11:43:55Z",
      "fields": {},
      "attribution": {
        "referrer": "https://creator.kit.com/jane-smith",
        "utm_source": "kit",
        "utm_medium": "referral",
        "utm_campaign": null,
        "utm_term": null,
        "utm_content": null,
        "source_type": "form_subscription",
        "source_name": "Jane Smith's Recommendations",
        "source_mechanism": "recommendations",
        "source_mechanism_id": null
      },
      "tags": [
        {
          "id": 2,
          "name": "Newsletter"
        }
      ],
      "location": {
        "city": "Austin",
        "state": "TX",
        "country": "US",
        "latitude": 30.27,
        "longitude": -97.74,
        "timezone": "America/Chicago"
      }
    },
    {
      "id": 202,
      "state": "active",
      "first_name": "Camille",
      "email_address": "camille@convertkit.dev",
      "created_at": "2023-02-10T11:43:55Z",
      "fields": {},
      "attribution": {
        "referrer": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "utm_term": null,
        "utm_content": null,
        "source_type": "api_subscription",
        "source_name": "Partner Integration",
        "source_mechanism": "api",
        "source_mechanism_id": 12345
      },
      "tags": [],
      "location": null
    },
    {
      "id": 203,
      "state": "active",
      "first_name": "Elliot",
      "email_address": "elliot@convertkit.dev",
      "created_at": "2023-02-13T11:43:55Z",
      "fields": {},
      "attribution": {
        "referrer": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "utm_term": null,
        "utm_content": null,
        "source_type": null,
        "source_name": null,
        "source_mechanism": null,
        "source_mechanism_id": null
      },
      "tags": [
        {
          "id": 3,
          "name": "Imported"
        }
      ],
      "location": {
        "city": null,
        "state": null,
        "country": null,
        "latitude": null,
        "longitude": null,
        "timezone": null
      }
    }
  ],
  "pagination": {
    "has_previous_page": false,
    "has_next_page": false,
    "start_cursor": "MjAyMy0wMS0yNyAxMTo0Mzo1NSBVVEM=",
    "end_cursor": "MjAyMy0wMi0xMyAxMTo0Mzo1NSBVVEM=",
    "per_page": 500
  }
}

{
  "errors": [
    "The access token is invalid"
  ]
}

{
  "errors": [
    "The status param must be `cancelled` if sort_field is `cancelled_at`"
  ]
}

Subscribers

List subscribers

Returns a cursor-paginated list of subscribers in the account. By default only active subscribers are returned — use status (active, inactive, bounced, complained, cancelled, or all) to widen the search. Look a subscriber up by exact email_address, filter by created_after/created_before and updated_after/updated_before, and sort with sort_field (id, updated_at, or cancelled_at) and sort_order.

Use include (comma-separated: attribution, tags, location, canceled_at) to embed extra fields on each subscriber — including canceled_at without status=cancelled returns a 422. Set slim=true to omit the fields object (custom field values) for a faster, smaller response.

For engagement-based searches (opens, clicks, sends), use Filter subscribers by engagement instead.

GET

subscribers

List subscribers

curl --request GET \
  --url https://api.kit.com/v4/subscribers \
  --header 'X-Kit-Api-Key: <api-key>'

require 'uri'
require 'net/http'

url = URI("https://api.kit.com/v4/subscribers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Kit-Api-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

const options = {method: 'GET', headers: {'X-Kit-Api-Key': '<api-key>'}};

fetch('https://api.kit.com/v4/subscribers', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.kit.com/v4/subscribers"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Kit-Api-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.kit.com/v4/subscribers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-Kit-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

import requests

url = "https://api.kit.com/v4/subscribers"

headers = {"X-Kit-Api-Key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "subscribers": [
    {
      "id": 200,
      "state": "active",
      "first_name": "Alice",
      "email_address": "alice@convertkit.dev",
      "created_at": "2023-01-27T11:43:55Z",
      "fields": {
        "category": "One"
      },
      "attribution": {
        "referrer": "https://t.co/abc123",
        "utm_source": "twitter",
        "utm_medium": "cpc",
        "utm_campaign": "spring_launch",
        "utm_term": "newsletter+for+creators",
        "utm_content": "hero_cta",
        "source_type": "form_subscription",
        "source_name": "Welcome Form",
        "source_mechanism": "landing_page",
        "source_mechanism_id": null
      },
      "tags": [
        {
          "id": 1,
          "name": "VIP"
        }
      ],
      "location": {
        "city": "Portland",
        "state": "OR",
        "country": "US",
        "latitude": 45.5,
        "longitude": -122.6,
        "timezone": "America/Los_Angeles"
      }
    },
    {
      "id": 201,
      "state": "active",
      "first_name": "Benito",
      "email_address": "benito@convertkit.dev",
      "created_at": "2023-02-03T11:43:55Z",
      "fields": {},
      "attribution": {
        "referrer": "https://creator.kit.com/jane-smith",
        "utm_source": "kit",
        "utm_medium": "referral",
        "utm_campaign": null,
        "utm_term": null,
        "utm_content": null,
        "source_type": "form_subscription",
        "source_name": "Jane Smith's Recommendations",
        "source_mechanism": "recommendations",
        "source_mechanism_id": null
      },
      "tags": [
        {
          "id": 2,
          "name": "Newsletter"
        }
      ],
      "location": {
        "city": "Austin",
        "state": "TX",
        "country": "US",
        "latitude": 30.27,
        "longitude": -97.74,
        "timezone": "America/Chicago"
      }
    },
    {
      "id": 202,
      "state": "active",
      "first_name": "Camille",
      "email_address": "camille@convertkit.dev",
      "created_at": "2023-02-10T11:43:55Z",
      "fields": {},
      "attribution": {
        "referrer": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "utm_term": null,
        "utm_content": null,
        "source_type": "api_subscription",
        "source_name": "Partner Integration",
        "source_mechanism": "api",
        "source_mechanism_id": 12345
      },
      "tags": [],
      "location": null
    },
    {
      "id": 203,
      "state": "active",
      "first_name": "Elliot",
      "email_address": "elliot@convertkit.dev",
      "created_at": "2023-02-13T11:43:55Z",
      "fields": {},
      "attribution": {
        "referrer": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "utm_term": null,
        "utm_content": null,
        "source_type": null,
        "source_name": null,
        "source_mechanism": null,
        "source_mechanism_id": null
      },
      "tags": [
        {
          "id": 3,
          "name": "Imported"
        }
      ],
      "location": {
        "city": null,
        "state": null,
        "country": null,
        "latitude": null,
        "longitude": null,
        "timezone": null
      }
    }
  ],
  "pagination": {
    "has_previous_page": false,
    "has_next_page": false,
    "start_cursor": "MjAyMy0wMS0yNyAxMTo0Mzo1NSBVVEM=",
    "end_cursor": "MjAyMy0wMi0xMyAxMTo0Mzo1NSBVVEM=",
    "per_page": 500
  }
}

{
  "errors": [
    "The access token is invalid"
  ]
}

{
  "errors": [
    "The status param must be `cancelled` if sort_field is `cancelled_at`"
  ]
}

Authorizations

X-Kit-Api-Key

string

header

required

Authenticate API requests via an API Key

Query Parameters

after

string | null

To fetch next page of results, use ?after=<end_cursor>

before

string | null

To fetch previous page of results, use ?before=<start_cursor>

created_after

string

Filter subscribers who have been created after this date (format yyyy-mm-dd)

created_before

string

Filter subscribers who have been created before this date (format yyyy-mm-dd)

email_address

string

include

string

Comma-separated list of additional fields to include on each subscriber. Valid options: attribution, tags, location, canceled_at. canceled_at may only be used together with status=cancelled.

include_total_count

boolean

Set to true to include the total_count in the response. This option can cause slow responses; if paging through results, request it only on the first page and reuse the value for subsequent pages.

per_page

number | null

Number of results per page. Default 500, maximum 1000.

slim

boolean

When true, omits expensive optional fields from the response. Produces a faster, smaller response — useful when extra fields are not needed.

sort_field

string

sort_order

enum<string>

Available options:

asc,

desc

status

enum<string>

Filter subscribers who have this status (active, inactive, bounced, complained, cancelled or all). Defaults to active.

Available options:

active,

inactive,

bounced,

complained,

cancelled,

all

updated_after

string

Filter subscribers who have been updated after this date (format yyyy-mm-dd)

updated_before

string

Filter subscribers who have been updated before this date (format yyyy-mm-dd)

Response

Returns subscriber attribution, tags, and primary location when requested via the include param

subscribers

object[]

required

Show child attributes

pagination

object

required

Show child attributes

Bulk create subscribers Create a subscriber

⌘I