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.
The Lists API V2 is supported by the following libraries
Python (https://github.com/klaviyo/python-klaviyo)
Ruby (https://github.com/klaviyo/ruby-klaviyo)
PHP (https://github.com/klaviyo/php-klaviyo)
Node.js (https://github.com/klaviyo/node-klaviyo)
https://a.klaviyo.com
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.
To view your API key, you need to log in.
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.
Create a new list.
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.
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": "PRIVATE_API_KEY",
"list_name": "my new list name",
}
Get a listing of all of the lists in an account.
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.
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": "PRIVATE_API_KEY",
}
[
{
"list_id": "abcDEF",
"list_name": "my list",
},
{
"list_id": "ABcdEF",
"list_name": "my other list",
},
]
Get information about a list.
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.
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": "PRIVATE_API_KEY",
}
{
"list_name": "my list",
"created": "2018-07-03T13:44:38Z",
"updated": "2018-07-03T13:44:38Z",
}
Update a list's properties.
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.
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": "PRIVATE_API_KEY",
"list_name": "my new list name",
}
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.
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.
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": "PRIVATE_API_KEY",
}
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 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.
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.
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": "PRIVATE_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 if profiles are on a list and not suppressed.
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.
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": "PRIVATE_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 and remove profiles from a list.
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.
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": "PRIVATE_API_KEY",
"emails": ["george.washington@example.com", "john.adams@example.com"]
}
Use this endpoint to add profiles to and remove profiles from Klaviyo lists without changing their subscription or suppression status.
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.
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.
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": "PRIVATE_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 if profiles are on a list.
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.
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": "PRIVATE_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 profiles from a list.
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.
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": "PRIVATE_API_KEY",
"emails": ["george.washington@example.com", "john.adams@example.com"],
"phone_numbers": ["+12223334444", "+15556667777"],
"push_tokens": ["03df25c845d460bcdad7802d2vf6fc1dfde97283bf75cc993eb6dca835ea2e2r"]
}
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.
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.
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": "PRIVATE_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
}
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.
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.
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": "PRIVATE_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
}