Lists API V2 Overview

This API is used for creating profiles and managing list memberships and subscriptions. It is organized around REST. The API endpoints were designed to be predictable and resource-oriented and use HTTP response codes to indicate API errors. This means a single resource or endpoint can and often does provide different functionality based on the HTTP verb used to access it. JSON must be used to send data to the API (except for GET and DELETE requests, which also accept URI parameters). JSON is returned in all responses from the API if there is content in the response.

This API currently only supports subscribing customers and adding customers to lists. If you would like to manage your segments you can do so from the lists and segments page.

API Endpoint

https://a.klaviyo.com

Summary of Resource URL Patterns

  • POST /api/v2/lists
  • GET /api/v2/lists
  • -
  • GET /api/v2/list/{LIST_ID}
  • PUT /api/v2/list/{LIST_ID}
  • DELETE /api/v2/list/{LIST_ID}
  • -
  • POST /api/v2/list/{LIST_ID}/subscribe
  • GET /api/v2/list/{LIST_ID}/subscribe
  • DELETE /api/v2/list/{LIST_ID}/subscribe
  • -
  • POST /api/v2/list/{LIST_ID}/members
  • GET /api/v2/list/{LIST_ID}/members
  • DELETE /api/v2/list/{LIST_ID}/members
  • -
  • GET /api/v2/list/{LIST_ID}/exclusions/all
  • -
  • GET /api/v2/group/{LIST_ID or SEGMENT_ID}/members/all

Authentication

Klaviyo's API is served over HTTPS and all requests must be authenticated. You authenticate to the Lists API V2 by providing one of your private API keys as part of each request. You can manage your private API keys from your account.

Your Private API key

To view your API key, you need to log in.

Rate Limiting

All of these endpoints are rate limited. You should be sure to check the response codes and retry requests that exceed the rate limit at a later time. A rate limited response will include a timestamp corresponding to when the endpoint will become available again.

Lists

Create a List

Create a new list.

Arguments

The arguments should be sent as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
list_name
string
The name that you would like to give to the list.
Response

Successful requests will return with HTTP OK responses. Invalid requests will be accompanied by an error message.

POST https://a.klaviyo.com/api/v2/lists { "api_key": API_KEY, "list_name": "my new list name", }

Get Lists

Get a listing of all of the lists in an account.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
Response

Successful requests will include a list of JSON objects containing the list ID and name for each list. Invalid requests will be accompanied by an error message.

GET https://a.klaviyo.com/api/v2/lists { "api_key": API_KEY, } [ { "list_id": "abcDEF", "list_name": "my list", }, { "list_id": "ABcdEF", "list_name": "my other list", }, ]

List Details

Get List Details

Get information about a list.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
Response

Successful requests will include a JSON object containing information about the list. Invalid requests will be accompanied by an error message.

GET https://a.klaviyo.com/api/v2/list/{LIST_ID} { "api_key": API_KEY, } { "list_name": "my list", "folder_name": "a folder name", "created": "2018-07-03T13:44:38Z", "updated": "2018-07-03T13:44:38Z", }

Update a List

Update a list's properties.

Arguments

The arguments should be sent as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
list_name
string
The name that you would like to give to the list.
Response

Successful requests will return with HTTP OK responses. Invalid requests will be accompanied by an error message.

PUT https://a.klaviyo.com/api/v2/list/{LIST_ID} { "api_key": API_KEY, "list_name": "my new list name", }

Delete a List

Delete a list from an account. This is a destructive operation and cannot be undone. It will also remove flow triggers associated with the list.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
Response

Successful requests will return with HTTP OK responses. Invalid requests will be accompanied by an error message.

DELETE https://a.klaviyo.com/api/v2/list/{LIST_ID} { "api_key": API_KEY, }

List Subscriptions

Use this endpoint to subscribe emails to a list or unsubscribe from a list. In addition to modifying list membership, this endpoint will also update suppressions for the specified profiles. This allows profiles that previously unsubscribed from a list to be re-subscribed to that list and receive emails again.

Subscribe to List

Subscribe or re-subscribe profiles to a list. Profiles will be single or double opted into the specified list in accordance with that list’s settings.

Arguments

The arguments should be sent as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
profiles
list of JSON objects
The profiles that you would like to subscribe. Each object in the list must have an email key. You can also provide additional properties as key-value pairs. If you are a GDPR compliant business, you will need to include $consent in your API call. $consent is a Klaviyo special property and only accepts the following values: "email", "web", "sms", "directmail", "mobile"
Response

Successful requests will return with HTTP OK responses. If the list is single opt-in then a list of records containing the email address and the corresponding profile ID will also be included. Invalid requests will be accompanied by an error message.

POST https://a.klaviyo.com/api/v2/list/{LIST_ID}/subscribe { "api_key": API_KEY, "profiles": [ { "email": "george.washington@example.com", "example_property": "valueA" }, { "email": "thomas.jefferson@example.com", "example_property": "valueB" } ] } [ { "id": "abcDEF", "email": "george.washington@example.com", }, { "id": "dEFAbc", "email": "thomas.jefferson@example.com", } ]

Check List Subscriptions

Check if profiles are on a list and not suppressed.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
emails
list of emails
The emails corresponding to the profiles that you would like to check.
Response

Successful requests will include a list of JSON objects corresponding to email addresses on the list, their profile IDs, and the date they were added to the list. If an email corresponds to a profile that is not on the list or is suppressed then no JSON object will be returned for that email. Invalid requests will be accompanied by an error message.

GET https://a.klaviyo.com/api/v2/list/{LIST_ID}/subscribe { "api_key": API_KEY, "emails": ["george.washington@example.com", "john.adams@example.com"] } [ { "id": "abcDEF", "email": "george.washington@example.com", "added": "2018-07-03T13:44:38Z" } ]

Unsubscribe from List

Unsubscribe and remove profiles from a list.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
emails
list of emails
The emails corresponding to the profiles that you would like to unsubscribe from the list.
Response

Successful requests will return with HTTP OK responses. Invalid requests will be accompanied by an error message.

DELETE https://a.klaviyo.com/api/v2/list/{LIST_ID}/subscribe { "api_key": API_KEY, "emails": ["george.washington@example.com", "john.adams@example.com"] }

List Memberships

Use this endpoint to add profiles to and remove profiles from Klaviyo lists without changing their subscription or suppression status.

Add to List

Add profiles to the a list. This endpoint is functionally equivalent to adding profiles to a list via a CSV upload and will immediately add profiles to the list. If you would like to subscribe profiles to a list and use the double opt-in settings for the list please use the subscribe endpoint.

Arguments

The arguments should be sent as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
profiles
list of JSON objects
The profiles that you would like to add to the list. Each object in the list must have an email key. You can also provide additional properties as key-value pairs.
Response

Successful requests will return with HTTP OK responses and a list of records containing the email address and the corresponding profile ID. Invalid requests will be accompanied by an error message.

POST https://a.klaviyo.com/api/v2/list/{LIST_ID}/members { "api_key": API_KEY, "profiles": [ { "email": "george.washington@example.com", "example_property": "valueA" }, { "email": "thomas.jefferson@example.com", "example_property": "valueB" } ] } [ { "id": "abcDEF", "email": "george.washington@example.com", }, { "id": "dEFAbc", "email": "thomas.jefferson@example.com", } ]

Check List Membership

Check if profiles are on a list.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
emails
list of emails
The emails corresponding to the profiles that you would like to check.
Response

Successful requests will include a list of JSON objects corresponding to email addresses on the list, their profile IDs, and the date they were added to the list. If an email does not correspond to a profile on the list then no JSON object will be returned for that email. Invalid requests will be accompanied by an error message.

GET https://a.klaviyo.com/api/v2/list/{LIST_ID}/members { "api_key": API_KEY, "emails": ["george.washington@example.com", "john.adams@example.com"] } [ { "id": "abcDEF", "email": "george.washington@example.com", "added": "2018-07-03T13:44:38Z" } ]

Remove from List

Remove profiles from a list.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
emails
list of emails
The emails corresponding to the profiles that you would like to remove from the list.
Response

Successful requests will return with HTTP OK responses. Invalid requests will be accompanied by an error message.

DELETE https://a.klaviyo.com/api/v2/list/{LIST_ID}/members { "api_key": API_KEY, "emails": ["george.washington@example.com", "john.adams@example.com"] }

List Exclusions

Get All Exclusions on a List

Get all of the emails that have been excluded from a list along with the exclusion reason and exclusion time. This endpoint uses batching to return the records, so for a large list multiple calls will need to be made to get all of the records.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
marker
int; OPTIONAL
A marker value returned by a previous GET call. Use this to grab the next batch of records.
Response

Successful requests will include a list of JSON objects containing an excluded email, the reason it is marked excluded, and the exclusion date and potentially a marker if there are more records available. Invalid requests will be accompanied by an error message.

GET https://a.klaviyo.com/api/v2/list/{LIST_ID}/exclusions/all { "api_key": API_KEY, } { "records": [ { "id": "abcDEF", "email": "george.washington@example.com", "reason": "Bounced", "created": "2018-07-03T13:44:38Z", }, { "id": "xzyABC", "email": "thomas.jefferson@example.com", "reason": "Unsubscribed", "created": "2018-07-03T13:44:38Z", }, ], "marker": 123456 }

Group Memberships

Get Group Member Emails

Get all of the emails in a given list or segment. This endpoint uses batching to return the records, so for a large list or segment multiple calls will need to be made to get all of the records.

Arguments

The arguments can be sent as URI parameters or as content type application/json. The API key can also be specified in the request header with the key api-key.

api_key
string
The API key for your account.
marker
int; OPTIONAL
A marker value returned by a previous GET call. Use this to grab the next batch of records.
Response

Successful requests will include a JSON object containing a list of records containing profile IDs and emails and potentially a marker if there are more records available. Invalid requests will be accompanied by an error message.

GET https://a.klaviyo.com/api/v2/group/{LIST_ID or SEGMENT_ID}/members/all { "api_key": API_KEY, } { "records": [ { "id": "abcDEF", "email": "george.washington@example.com" }, { "id": "xzyABC", "email": "thomas.jefferson@example.com" }, ], "marker": 123456 }