The Lists & List Management API is used for creating and managing lists in Klaviyo. This API 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 is returned in all responses from the API, including errors.
This API only currently supports creating and managing standard lists. If you'd like to create a new segment, you can do so from the lists and segments page.
We are working on adding the Lists & List Management API to our existing libraries. If you want to be notified when those libraries have been updated you can watch the following repositories:
Python (https://github.com/klaviyo/python-klaviyo)
Ruby (https://github.com/klaviyo/ruby-klaviyo)
PHP (https://github.com/klaviyo/php-klaviyo)
https://a.klaviyo.com
You authenticate to the Lists & List Management API by providing one of your private API keys as part of each request. You can manage your private API keys from your account. We allow you to have multiple API keys at once in case you need more than one.
Authentication happens via the api_key parameter in each request. It can be sent as part of the GET or POST parameters.
Klaviyo's API is served over HTTPS and all requests must be authenticated.
To view your API key, you need to log in.
Our API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error from information provided as part of the request (e.g. the requested object doesn't exist, an invalid setting, etc.), and codes in the 5xx range indicate an error on Klaviyo's end.
The response of all API errors contain a message parameter which has developer-facing information about why the request failed.
When we make backwards incompatible changes to the API, we release new API versions, which are reflected in the API endpoints. The current version, v1, is the first version. In the future, if we switch to v2, we will provide documentation on the changes as well as new documentation detailing how to use the new API.
List objects represent standard (e.g. not dynamic) lists of people. With lists, you can send campaigns and manage individual subscriptions.
Returns a list of all the lists and segments in your account. The lists and segments are returned in sorted by their creation date.
A dictionary with a data property that contains an array of all the lists. Each entry is a separate list object. If no lists exist, the resulting array will be empty. This request should never return an error.
GET https://a.klaviyo.com/api/v1/lists
curl https://a.klaviyo.com/api/v1/lists -G \
-d api_key=API_KEY
{
"object": "$list",
"start" : 0,
"end": 3,
"page" : 0,
"page_size": 3,
"total": 3,
"data": [
{
"object": "list",
"id": "dqQnNW",
"name": "Newsletter Subscribers",
"type": "standard",
"created": "2013-06-10 13:00:00",
"updated": "2013-06-17 14:00:00",
"person_count": 1000
},
{...},
{...}
]
}
Create a new list. Currently this resources only supports creating standard lists.
The newly created List object with summary information.
POST https://a.klaviyo.com/api/v1/lists
curl https://a.klaviyo.com/api/v1/lists \
-X POST \
-d api_key=API_KEY \
-d "name=My New List" \
-d list_type=standard
{
"object": "list",
"id" : "dqQnNW",
"name": "My New List",
"list_type": "standard",
"created": "2013-06-17 14:00:00",
"updated": "2013-06-17 14:00:00",
"person_count": 0
}
Summary information for the list specified that includes the name, ID, type, number of members, when it was created and last updated.
There are no arguments for this method.
The List object with summary information.
GET https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}
curl https://a.klaviyo.com/api/v1/list/dqQnNW -G \
-d api_key=API_KEY \
{
"object": "list",
"id" : "dqQnNW",
"name": "Newsletter Subscribers",
"list_type": "standard",
"created": "2013-06-10 13:00:00",
"updated": "2013-06-17 14:00:00",
"person_count": 1000
}
Update details of the list. Currently this only support updating the name of the list.
The List object with summary information including updated details.
PUT https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}
curl https://a.klaviyo.com/api/v1/list/dqQnNW \
-X PUT \
-d api_key=API_KEY \
-d "name=My New List Name"
{
"object": "list",
"id" : "dqQnNW",
"name": "New List Name",
"list_type": "standard",
"created": "2013-06-10 13:00:00",
"updated": "2013-06-17 14:00:00",
"person_count": 1000
}
Deletes a list. This will also disable any autoresponders associated with this list.
Note: This is a destructive operation and cannot be undone. Be careful when deleting objects.
There are no arguments for this method.
The deleted Email Template object with summary information.
DELETE https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}
curl https://a.klaviyo.com/api/v1/list/dqQnNW \
-X DELETE \
-d api_key=API_KEY
{
"object": "list",
"name": "New List Name",
"list_type": "standard",
"created": "2013-06-10 13:00:00",
"updated": "2013-06-17 14:00:00"
}
Check if one or more people are already members of the specified list, based on their e-mail addresses. No distinction is made between a person not being subscribed to the list, and not being present in Klaviyo at all.
An array of Membership objects.
GET https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}/members
curl https://a.klaviyo.com/api/v1/list/dqQnNW/members -G \
-d api_key=API_KEY \
-d email='["george.washington@example.com","thomas.jefferson@example.com"]'
curl https://a.klaviyo.com/api/v1/list/dqQnNW/members -G \
-d api_key=API_KEY \
-d email='george.washington@example.com,thomas.jefferson@example.com'
curl https://a.klaviyo.com/api/v1/list/dqQnNW/members -G \
-d api_key=API_KEY \
-d email=george.washington@example.com
{
"object": "$list",
"start" : 0,
"end": 1,
"page" : 0,
"page_size": 2,
"total": 2,
"data": [
{
"object": "membership",
"email": "george.washington@example.com",
"date_added": "2013-06-10 13:00:00",
"person": {
"object": "person",
"id": "0mzwQ7",
"$email": "george.washington@example.com",
"$first_name": "George",
"$last_name": "Washington",
"$organization": "U.S. Government",
"$title": "President",
"$city": "Mount Vernon",
"$region": "Virginia",
"$zip": "22121"
"$country": "United States",
"$timezone": "US/Eastern",
"$phone_number": "",
}
},
{
"object": "membership",
"email": "thomas.jefferson@example.com",
"date_added": "2013-06-10 13:00:00",
"person": {
"object": "person",
"id": "4UaYpQ",
"$email": "thomas.jefferson@example.com",
"$first_name": "Thomas",
"$last_name": "Jefferson",
"$organization": "U.S. Government",
"$title": "President",
"$city": "Charlottesville",
"$region": "Virginia",
"$zip": "22902",
"$country": "United States",
"$timezone": "US/Eastern",
"$phone_number": "",
}
}
]
}
Check if one or more people are already members of the specified segment, based on their e-mail addresses. No distinction is made between a person not being subscribed to the segment, and not being present in Klaviyo at all.
An array of Membership objects.
GET https://a.klaviyo.com/api/v1/segment/{{ SEGMENT_ID }}/members
curl https://a.klaviyo.com/api/v1/segment/dqQnNW/members -G \
-d api_key=API_KEY \
-d email='["george.washington@example.com","thomas.jefferson@example.com"]'
curl https://a.klaviyo.com/api/v1/segment/dqQnNW/members -G \
-d api_key=API_KEY \
-d email='george.washington@example.com,thomas.jefferson@example.com'
curl https://a.klaviyo.com/api/v1/segment/dqQnNW/members -G \
-d api_key=API_KEY \
-d email=george.washington@example.com
{
"object": "$list",
"start" : 0,
"end": 1,
"page" : 0,
"page_size": 2,
"total": 2,
"data": [
{
"object": "membership",
"email": "george.washington@example.com",
"date_added": "2013-06-10 13:00:00",
"person": {
"object": "person",
"id": "0mzwQ7",
"$email": "george.washington@example.com",
"$first_name": "George",
"$last_name": "Washington",
"$organization": "U.S. Government",
"$title": "President",
"$city": "Mount Vernon",
"$region": "Virginia",
"$zip": "22121"
"$country": "United States",
"$timezone": "US/Eastern",
"$phone_number": "",
}
},
{
"object": "membership",
"email": "thomas.jefferson@example.com",
"date_added": "2013-06-10 13:00:00",
"person": {
"object": "person",
"id": "4UaYpQ",
"$email": "thomas.jefferson@example.com",
"$first_name": "Thomas",
"$last_name": "Jefferson",
"$organization": "U.S. Government",
"$title": "President",
"$city": "Charlottesville",
"$region": "Virginia",
"$zip": "22902",
"$country": "United States",
"$timezone": "US/Eastern",
"$phone_number": "",
}
}
]
}
Adds a new person to the specified list. If a person with that email address does not already exist, a new person is first added to Klaviyo. If someone is unsubscribed from the specified list, they will not be subscribed. To re-subscribe someone, you must manually remove them from the unsubscribe list in Klaviyo on the members page for the specified list.
A Person and List object corresponding to the added person and the list they were added to, respectively. There is an additional already_member flag that indicates whether this individual was already a member of this list. When confirm_optin is set to true in a request, the person.id will always return as null in the response. This is because until a new subscriber confirms his/her subscription, a profile for this person will not be generated in Klaviyo.
POST https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}/members
curl https://a.klaviyo.com/api/v1/list/dqQnNW/members \
-X POST \
-d api_key=API_KEY \
-d email=george.washington@example.com \
-d properties='{ "$first_name" : "George", "Birthday" : "02/22/1732" }' \
-d confirm_optin=true
{
"person": {
"object": "person",
"id": null,
"email": "george.washington.@example.com"
},
"list": {
"object": "list",
"id": "dqQnNW",
"name": "Newsletter Subscribers"
},
"already_member": false
}
Adds multiple people to the specified list. For each person, if a person with that email address does not already exist, a new person is first added to Klaviyo. If someone is unsubscribed from the specified list, they will not be subscribed. To re-subscribe someone, you must manually remove them from the unsubscribe list in Klaviyo on the members page for the specified list.
email key which is the email address of the person to add. The dictionary may also contain an optional properties dictionary which contains properties to identify each person. This is useful if you have additional information such as someone's name or custom properties such as someone's birthday you'd like to associate with their profile.An array of objects for each person added with a Person object included as well as a List object corresponding to the list they were added to. An already_member flag is included part of each object in the array that indicates whether this individual was already a member of this list. When confirm_optin is set to true in a request, the person.id will always return as null in the response. This is because until a new subscriber confirms his/her subscription, a profile for this person will not be generated in Klaviyo.
POST https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}/members/batch
curl https://a.klaviyo.com/api/v1/list/dqQnNW/members/batch \
-X POST \
-d api_key=API_KEY \
-d batch='[ { "email" : "george.washington@example.com", "properties" : { "$first_name" : "George", "Birthday" : "02/22/1732" } }, { "email" : "thomas.jefferson@example.com" } ]' \
-d confirm_optin=true
{
"people": [
{
"person" : {
"object": "person",
"id": "erRoOX",
"email": "george.washington@example.com"
},
"already_member": true,
},
{
"person" : {
"object": "person",
"id": "fsSpPY",
"email": "thomas.jefferson@example.com"
},
"already_member": false,
}
],
"list": {
"object": "list",
"id": "dqQnNW",
"name": "Newsletter Subscribers"
}
}
Removes multiple people from the specified list. For each person, if a person with that email address is a member of that list, they are removed.
email key which is the email address of the person to remove.An array of Person objects as well as a List object corresponding to the list they were added to. If email addresses are included that are not part of your Klaviyo account are included as a list of Person objects, an additional "unknown_people" key is added.
DELETE https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}/members/batch
curl https://a.klaviyo.com/api/v1/list/dqQnNW/members/batch \
-X DELETE \
-d api_key=API_KEY \
-d batch='[ { "email" : "george.washington@example.com" }, { "email" : "ben.franklin@example.com" } ]'
{
"people": [
{
"person" : {
"object": "person",
"id": "erRoOX",
"email": "george.washington@example.com"
}
}
],
"unknown_people" : [
{
"person" : {
"object": "person",
"email": "thomas.jefferson@example.com"
}
}
]
"list": {
"object": "list",
"id": "dqQnNW",
"name": "Newsletter Subscribers"
}
}
Marks a person as excluded from the specified list. This has the same effect as unsubscribing someone from a list, except we keep track of the fact that they did not use the unsubscribe link in your campaigns or on your list preferences page. This is equivalent to manually excluding someone on the list members page. Someone who is excluded will no longer receive campaigns or flow emails for this list.
Keep in mind, there is currently no API to un-exclude someone. Re-adding them will not un-exclude them. In order to remove this block, you must go to the members page for the list and manually change their status.
An already_excluded flag that indicates whether this individual was already excluded.
POST https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}/members/exclude
curl https://a.klaviyo.com/api/v1/list/dqQnNW/members/exclude \
-X POST \
-d api_key=API_KEY \
-d email=george.washington@example.com
{
"already_excluded": false
}
Get all the exclusions for the specified list. This will include the person's email, the reason they were excluded and the time they were excluded.
unsubscribed, bounced, invalid_email, reported_spam and manually_excluded. Only a single value be specified at a time.asc or desc. Defaults to asc.
An array of Exclusion objects.
GET https://a.klaviyo.com/api/v1/list/{{ LIST_ID }}/exclusions
curl https://a.klaviyo.com/api/v1/list/dqQnNW/exclusions -G \
-d api_key=API_KEY \
-d reason=unsubscribe
{
"object": "$list",
"start" : 0,
"end": 100,
"page" : 0,
"page_size": 100,
"total": 200,
"data": [
{
"object": "exclusion",
"email": "george.washington@example.com",
"reason" : "unsubscribed",
"timestamp": "2013-06-10 13:00:00"
},
{...},
{...}
]
}
The Exclusions API allows you to exclude or unsubscribe people from all campaigns across all lists. Use this API when you want to exclude someone from all future campaigns, regardless of which list it is sent to. If you want to exclude someone only from a specific list, use the exclude endpoint for that list.
Exclusions are equivalent to unsubscribes, except they are initiated by you, not by someone clicking an unsubscribe link. We make this distinction so it's easy to see what caused someone to stop receiving email.
Get global exclusions or unsubscribes. Global exclusions are distinct from list exclusions in that these email addresses will not receive any emails from any list. Typically, when someone unsubscribes from a campaign, they are only unsubscribed from that list and are not globally unsubscribed.
This will include the person's email, the reason they were excluded and the time they were excluded.
unsubscribed, bounced, invalid_email, reported_spam and manually_excluded. Only a single value be specified at a time.asc or desc. Defaults to asc.
An array of Exclusion objects.
GET https://a.klaviyo.com/api/v1/people/exclusions
curl https://a.klaviyo.com/api/v1/people/exclusions -G \
-d api_key=API_KEY \
-d reason=unsubscribe
{
"object": "$list",
"start" : 0,
"end": 100,
"page" : 0,
"page_size": 100,
"total": 200,
"data": [
{
"object": "exclusion",
"email": "george.washington@example.com",
"reason" : "unsubscribed",
"timestamp": "2013-06-10 13:00:00"
},
{...},
{...}
]
}
Marks a person as excluded from all email. This works the same way as manually excluding someone through on the excluded people page. Someone who is excluded will no longer receive any campaigns or flow emails.
Keep in mind, there is currently no API to un-exclude someone. In order to remove this block, you must manually remove someone from the unsubscribed list.
An already_excluded flag that indicates whether this individual was already unsubscribed from all email.
POST https://a.klaviyo.com/api/v1/people/exclusions
curl https://a.klaviyo.com/api/v1/people/exclusions \
-X POST \
-d api_key=API_KEY \
-d email=george.washington@example.com
{
"already_excluded": false
}