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", "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 and/or phone numbers to a list. You can use this endpoint to unsubscribe them from a list as well. In addition to modifying list membership, this endpoint will also update email address 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. Note, if you have not completed setup for SMS in Klaviyo you will not be able to issue consent for phone numbers or send opt in SMS messages to phone numbers with this endpoint.

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 either an email or phone number 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". If you are updating consent for a phone number or would like to send an opt-in SMS to the profile (for double opt-in lists), include an sms_consent key in the profile with a value of true or false.
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, phone number, push token, 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", "phone_number": "+12223334444", "sms_consent": true, "example_property": "valueB" } ] } [ { "id": "abcDEF", "email": "george.washington@example.com", }, { "id": "dEFAbc", "email": "thomas.jefferson@example.com", "phone_number": "+12223334444" } ]

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.
phone_numbers
list of phone numbers
The phone numbers corresponding to the profiles that you would like to check. Phone numbers must be in E.164 format.
push_tokens
list of push tokens
The push tokens corresponding to the profiles that you would like to check.
Response

Successful requests will include a list of JSON objects corresponding to email addresses, phone numbers, and/or push tokens on the list, their profile IDs, and the date they were added to the list. If an identifier corresponds to a profile that is not on the list or is suppressed then no JSON object will be returned for that profile. If a profile shares multiple provided identifiers (such as an email address and a phone number) only a single profile is returned, not two. Only profiles that have consented to receive SMS will include their phone number in the response. 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"], "phone_numbers": ["+12223334444", "+15556667777"], "push_tokens": ["03df25c845d460bcdad7802d2vf6fc1dfde97283bf75cc993eb6dca835ea2e2r"] } [ { "id": "abcDEF", "email": "george.washington@example.com", "created": "2018-07-03T13:44:38Z" }, { "id": "CHoNUs", "email": "john.adams@example.com", "phone_number": "+12223334444", "created": "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 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, phone_number, or push_token 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 corresponding profile ID, email address, phone number, and push token. 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", "phone_number": "+12223334444", "example_property": "valueB" } ] } [ { "id": "abcDEF", "email": "george.washington@example.com", }, { "id": "dEFAbc", "email": "thomas.jefferson@example.com", "phone_number": "+12223334444" } ]

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.
phone_numbers
list of phone numbers
The phone numbers corresponding to the profiles that you would like to check. Phone numbers must be in E.164 format.
push_tokens
list of push tokens
The push tokens corresponding to the profiles that you would like to check.
Response

Successful requests will return a list of JSON objects corresponding to email addresses, phone numbers, push tokens, their profile IDs, and the date they were added to the list. If an identifier does not correspond to a profile on the list then no JSON object will be returned for that identifier. 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"], "phone_numbers": ["+12223334444", "+15556667777"], "push_tokens": ["03df25c845d460bcdad7802d2vf6fc1dfde97283bf75cc993eb6dca835ea2e2r"] } [ { "id": "abcDEF", "email": "george.washington@example.com", "created": "2018-07-03T13:44:38Z" }, { "id": "CHoNUs", "email": "john.adams@example.com", "phone_number": "+12223334444", "created": "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.
phone_numbers
list of phone numbers
The phone numbers corresponding to the profiles that you would like to remove from the list. Phone numbers must be in E.164 format.
push_tokens
list of push tokens
The push tokens 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"], "phone_numbers": ["+12223334444", "+15556667777"], "push_tokens": ["03df25c845d460bcdad7802d2vf6fc1dfde97283bf75cc993eb6dca835ea2e2r"] }

List Exclusions

Get All Exclusions on a List

Get all of the emails and phone numbers that have been excluded from a list along with the exclusion reasons 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. If the profile has a valid phone number, it is returned as well, along with the phone_reason for phone numbers with revoked consent. 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", "phone_number": "+12223334444", "phone_reason": "Unsubscribed" }, ], "marker": 123456 }

Group Memberships

Get Group Member Identifiers

Get all of the emails, phone numbers, and push tokens for profiles 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, emails, phone numbers, push tokens, 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", "phone_number": "+12223334444", "push_token": "03df25c845d460bcdad7802d2vf6fc1dfde97283bf75cc993eb6dca835ea2e2r" }, ], "marker": 123456 }