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.
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": 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": 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": 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'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": 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": API_KEY,
}
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 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 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 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 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 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": 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 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.
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 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 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 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 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": API_KEY,
"emails": ["george.washington@example.com", "john.adams@example.com"]
}
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.
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. 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
}
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.
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 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
}