Lists & List Management API Overview

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.

Libraries

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)

API Endpoint

https://a.klaviyo.com

Summary of Resource URL Patterns

  • GET /api/v1/lists
  • POST /api/v1/lists
  • GET /api/v1/list/{LIST_ID}
  • PUT /api/v1/list/{LIST_ID}
  • DELETE /api/v1/list/{LIST_ID}
  • GET /api/v1/list/{LIST_ID}/members
  • GET /api/v1/segment/{SEGMENT_ID}/members
  • POST /api/v1/list/{LIST_ID}/members
  • POST /api/v1/list/{LIST_ID}/members/batch
  • POST /api/v1/list/{LIST_ID}/members/exclude
  • GET /api/v1/list/{LIST_ID}/exclusions
  • GET /api/v1/people/exclusions
  • POST /api/v1/people/exclusions

Authentication

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.

Your Private API key

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

Errors

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.

HTTP Status Code Summary

  • 200 OK - The request completed successfully.
  • 400 Bad request - Request is missing or has a bad parameter.
  • 400 Not Authorized - Request is missing or has an invalid API key.
  • 404 Not Found - The requested resource doesn't exist.
  • 500 Server errors - Something is wrong on Klaviyo's end.

Versioning

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.

Lists

List objects represent standard (e.g. not dynamic) lists of people. With lists, you can send campaigns and manage individual subscriptions.

Lists in Account

DEPRECATED: Please use the Lists API V2.

Returns a list of all the lists and segments in your account. The lists and segments are returned in sorted by their creation date.

Arguments
type
optional, string, either "list" or "segment"
If specified, filter results to include only lists or segments.
page
optional, integer, defaults to 0
For pagination, which page of results to return.
count
optional, integer, defaults to 50
For pagination, the number of results to return. The maximum number is 100.
Response

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 }, {...}, {...} ] }

Creating a List

DEPRECATED: Please use the Lists API V2.

Create a new list. Currently this resources only supports creating standard lists.

Arguments
name
string
The name of the list.
list_type
string
This must be set to standard. In the future this resource will also support the dynamic list type.
Response

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 }

List Information

DEPRECATED: Please use the Lists API V2.

Summary information for the list specified that includes the name, ID, type, number of members, when it was created and last updated.

Arguments

There are no arguments for this method.

Response

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 }

Updating a List

DEPRECATED: Please use the Lists API V2.

Update details of the list. Currently this only support updating the name of the list.

Arguments
context
name, string
A new name to assign to this list.
Response

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 }

Deleting a List

DEPRECATED: Please use the Lists API V2.

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.

Arguments

There are no arguments for this method.

Response

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" }

Checking if Someone is in a List

DEPRECATED: Please use the Lists API V2.

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.

Arguments
email
email address
A single email address or JSON-encoded list of email addresses to look for in the specified list.
Response

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": "", } } ] }

Checking if Someone is in a Segment

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.

Arguments
email
email address
A single email address or JSON-encoded list of email addresses to look for in the specified segment.
Response

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": "", } } ] }

Adding Someone to a List

DEPRECATED: Please use the Lists API V2.

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.

Arguments
email
email address
The email address of the person who will be added to the list.
properties
optional, JSON encoded dictionary
Additional properties to assign to this 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. See the People API for more information about properties.
If you are a GDPR compliant business, you'll want to include $consent in your API call. $consent is a list type, Klaviyo special property and only accepts the following values ["email", "web", "sms", "directmail", "mobile"].
confirm_optin
optional, boolean
This flag determines whether someone is sent an email with a confirmation link before they are added to the list. Defaults to true. This should only be set to false if you have already received explicit permission from this person to add them to this list. Inappropriately setting this flag to false without explicit permission of the people added can result in account suspension and/or termination.
Response

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 }

Batch Adding People to a List

DEPRECATED: Please use the Lists API V2.

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.

Arguments
batch
JSON encoded array of dictionaries
Each dictionary should contain an 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.
confirm_optin
optional, boolean
This flag determines whether someone is sent an email with a confirmation link before they are added to the list. Defaults to true. This should only be set to false if you have already received explicit permission from this person to add them to this list. Inappropriately setting this flag to false without explicit permission of the people added can result in account suspension and/or termination.
Response

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" } }

Batch Removing People from a List

DEPRECATED: Please use the Lists API V2.

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.

Arguments
batch
JSON encoded array of dictionaries
Each dictionary should contain an email key which is the email address of the person to remove.
Response

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" } }

Exclude or Unsubscribe Someone from a List

DEPRECATED: Please use the Lists API V2.

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.

Arguments
email
email address
The email address of the person who will be excluded from the list.
Response

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 }

List Exclusions or Unsubscribes for a List

DEPRECATED: Please use the Lists API V2.

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.

Arguments
reason
optional, string
Filter results based on the reason for someone being excluded. The possible values are unsubscribed, bounced, invalid_email, reported_spam and manually_excluded. Only a single value be specified at a time.
sort
optional, string
Order results chronologically, in ascending or descending order. The possible values are asc or desc. Defaults to asc.
Response

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" }, {...}, {...} ] }

Exclusions

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.

List Exclusions or Unsubscribes

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.

Arguments
reason
optional, string
Filter results based on the reason for someone being excluded. The possible values are unsubscribed, bounced, invalid_email, reported_spam and manually_excluded. Only a single value be specified at a time.
sort
optional, string
Order results chronologically, in ascending or descending order. The possible values are asc or desc. Defaults to asc.
Response

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" }, {...}, {...} ] }

Exclude or Unsubscribe Someone from All Email

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.

Arguments
email
email address
The email address of the person who will be excluded.
Response

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 }