GET subscriptions data functionality (corresponding to GET /api/v1/people/exclusions and POST /api/v2/list/{list_id}/get-list-subscriptions in our v1-2 APIs)
The functionality above is still available via our v1-2 APIs, which can be found by selecting v1-2 from the dropdown in the upper left and navigating to the API Reference.
Comparison chart: v1/v2 and corresponding new API endpoints
This table covers improved functionality for endpoints in Klaviyo’s new APIs that have corresponding endpoints in our v1/v2 APIs. New endpoints that have no corresponding older version are listed in a separate table below. Note that some v1/v2 endpoints correspond to multiple new endpoints for different uses.
v1/v2 endpoint
Supported features
New endpoint
Supported features
GET
/api/v1/metrics
Get all metrics in an account
Returns 50 to 100 results per page
Returns a page based on a specified integer
GET
/api/metrics
Get all metrics in an account
Request specific fields with sparse fieldsets
Filter requests by specific fields, including integration.category and integration.name
Returns 200 results per page
Cursor-based pagination
GET
/api/v1/metrics/timeline
Returns a batched timeline of all events in your account
Number of events to return in a batch: default = 50, max = 100
Sort order for timeline either descending or ascending
GET
/api/events
Get all events in an account
Requests can be sorted by the following fields: datetime, timestamp
Use filters to narrow your results to specific metrics
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: metrics, profiles
Returns a maximum of 200 events per page, which can be paginated with cursor-based pagination
GET
api/v1/metric/{metric_id}/
timeline
Returns a batched timeline for one specific metric
Number of events to return in a batch, max = 100
Sort order for timeline either descending or ascending
GET
/api/events?filter=equals
(metric_id,”{metric_id}”)
Get all events for a single metric
Requests can be sorted by the following fields: datetime, timestamp
Use filters to narrow your results to specific metrics
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: metrics, profiles
Returns a maximum of 200 events per page, which can be paginated with cursor-based pagination
GET
/api/v1/metric/{metric_id}/
export
Exports event data from Klaviyo, optionally filtering and segmenting on available event properties.
Note that the only comparison operator currently supported is =
POST
/api/metric-aggregates
Query and aggregate event data associated with a metric, including native Klaviyo metrics, integration-specific metrics, and custom events
Query passed in JSON request body
Major bug fix for long-standing issue with dimensions with greater than 1000 values
Results can be filtered and grouped by time, event, or profile dimensions
Request specific fields using sparse fieldsets
Simplified filter syntax consistent with other endpoints
POST
/api/track
Create a new event to track a profile’s activity
Can accept payloads up to approximately 1 MB
POST
/client/events
Create a new event to track a profile’s activity, designed to be called from publicly-browseable, client-side environments only
To create events from server-based applications, please use POST /api/events
Accepts plain application/json, rather than application/x-www-form-urlencoded payloads, like the old endpoints
POST
/api/track
Create a new event to track a profile’s activity
Can accept payloads up to approximately 1 MB
POST
/api/events
Create a new event, designed to be called from a server-based application
To create events called from a publicly-browsable, client-side environment, please use POST /client/events
POST
/api/identify
Track and update properties about an individual without tracking an associated event
POST
/client/profiles
Create and update properties about a profile without tracking an associated event, designed to be called from publicly-browseable, client-side environments
To create profiles from server-based applications, please use POST /api/profiles
Accepts plain application/json, rather than application/x-www-form-urlencoded payloads, like the old endpoints
POST
/api/identify
Track and update properties about an individual without tracking an associated event
POST
/api/profiles
Create and update profiles, designed to be called from a server-based application
To create profiles called from publicly-browseable, client-side environments, use POST /client/profiles
POST
/api/identify
Track and update properties about an individual without tracking an associated event
PATCH
/api/profiles/{id}/
Update a profile with the given profile ID
POST
/ajax/subscriptions
This endpoint was never publicly documented
POST
/client/subscriptions
Create a new subscription for the given list ID and channel: Email isemail, SMS is phone_number
Designed to be called from publicly-browseable, client-side environments
To create subscriptions from server-based applications, use POST /api/profile-subscription-bulk-create-jobs
POST
/ajax/subscriptions
This endpoint was never publicly documented
POST
/api/profile-subscription-
bulk-create-jobs
Subscribe one or more profiles to email marketing, SMS marketing, or both
Designed to be called from server-based applications
To create subscriptions from publicly-browseable, client-side environments, use POST /client/subscriptions
POST
/api/v1/people/exclusions
Marks a person as excluded from all email
This works the same way as manually excluding someone via the excluded people page
Someone who is excluded will no longer receive any campaigns or flow emails
POST
/api/profile-suppression-
bulk-create-jobs/
Suppress one or more profiles
This works the same way as manually excluding someone via the excluded people page
Suppressed profiles will not receive email marketing
Not supported for SMS marketing
POST
/api/v2/people/exchange
Klaviyo's web tracking uses an encrypted identifier. However, there are many use cases that require developers to have access to a given profile's email or phone number
In such cases, developers can use this operation to exchange an encrypted identifier for a profile ID, which they can then use to retrieve the full profile data (by making a subsequent request to the get-profiles operation)
GET
/api/profiles?filter=equals
(_kx,"{kx_token}")
Get all profiles in an account
Profiles can be sorted by the following fields in ascending and descending order: id, created, email
Use filters to narrow your results
Request specific fields using sparse fieldsets
Use filtering by the Klaviyo _kx identifier
PUT
/api/v1/person/{person_id}
Add or update one or more attributes for a Person, based on the Klaviyo Person ID. If a property already exists, it will be updated. If a property is not set for that record, it will be created
For creating or updating a profile in v1/v2, you should be using the Identify API instead
The best use case for this endpoint is changing a profile's email address or other primary identifier after a profile already exists in Klaviyo
POST
/api/profiles/
Create and update profiles, designed to be called from a server-based application
To create profiles called from publicly-browseable, client-side environments, use POST /client/profiles
PUT
/api/v1/person/{person_id}
Add or update one or more attributes for a Person, based on the Klaviyo Person ID. If a property already exists, it will be updated. If a property is not set for that record, it will be created
For creating or updating a profile in v1/v2, you should be using the Identify API instead
The best use case for this endpoint is changing a profile's email address or other primary identifier after a profile already exists in Klaviyo
PATCH
/api/profiles/{id}/
Update a profile with the given profile ID
GET /api/v1/person/{person_id}
Retrieves all the data attributes for a person, based on the Klaviyo Person ID
GET
/api/profiles/{id}/
Get a profile with the given profile ID
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: lists, memberships, segments memberships
GET
/api/v2/group/
{list_or_segment_id}/
members/all
Gets all of the emails, phone numbers, and push tokens for profiles in a given list or segment
GET
/api/lists/{list_id}/profiles/
Get all profiles within a list with the given list ID
Retrieves full profile information for each list member (not just emails, phone numbers, and push tokens)
Use filters to narrow your results
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET
/api/v2/group/
{list_or_segment_id}/
members/all
Gets all of the emails, phone numbers, and push tokens for profiles in a given list or segment
GET
/api/segments/
{segment_id}/profiles/
Get all profiles within a segment with the given segment ID
Retrieves full profile information for each segment member (not just emails, phone numbers, and push tokens)
Filter to request a subset of all profiles. Profiles can be filtered by email, phone_number, and push_token fields
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
POST
/api/v2/list/{list_id}/
subscribe
Subscribe profiles to a list
Profiles will be single or double opted into the specified list in accordance with that list’s settings. Note: If you have double opt-in enabled (default behavior), users will not be added to the list until they opt in, and so the API will respond with an empty list
POST
/api/profile-subscription-
bulk-create-jobs/
Subscribe one or more profiles to email marketing, SMS marketing, or both
DELETE
/api/v2/list/{list_id}/
subscribe
Unsubscribe and remove profiles from a list
POST
/api/profile-unsubscription-bulk-
create-jobs/
Unsubscribe one or more profiles from email marketing, SMS marketing, or both
POST
/api/v2/lists
Create a new list
POST
/api/lists/
Create a new list
GET
/api/v2/lists
Return a listing of all the lists in an account
GET
/api/lists/
Get all lists in an account
Use filters to narrow your results
Request specific fields using sparse fieldsets
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET
/api/v2/list/{list_id}
Return information about a list
GET
/api/lists/{id}/
Get a list with the given list ID
PUT
/api/v2/list/{list_id}
Update a list's name
PATCH
/api/lists/{id}/
Update the name of a list with the given list ID
POST
/api/v2/list/{list_id}/
members
Add profiles to a list with the given list ID
POST
/api/lists/{id}/relationships/
{related_resource}/
Add a profile to a list with the given list ID
DELETE
/api/v2/list/{list_id}/
members
Remove profiles from a list with the given list ID
Remove a profile from a list with the given list ID
DELETE
/api/v2/list/{list_id}
Delete a list with the given list ID
This is a destructive operation and cannot be undone
It will also remove flow triggers associated with the list
DELETE
/api/lists/{id}/
Delete a list with the given list ID
GET
/api/v1/email-templates
Return a list of all the email templates you've created
The templates are returned in sorted order by name
GET
/api/templates
Get all templates in an account
Filter to request a subset of all templates. Templates can be sorted by the following fields, in ascending and descending order: id, name, created, updated
Request specific fields using sparse fieldsets
Returns a maximum of 20 results per page. Results can be paginated with cursor-based pagination
POST
/api/v1/email-templates
Create a new custom HTML email template
POST
/api/templates
Create a new custom HTML email template
Request specific fields using sparse fieldsets
PUT
/api/v1/email-
template/{template_id}
Update a template with the given template ID
Only updates imported HTML templates; does not update drag and drop templates
PATCH
/api/templates/{id}/
Update a template with the given template ID
Request specific fields using sparse fieldsets
Only updates imported HTML templates; does not update drag and drop templates
DELETE
/api/v1/email-template/
{template_id}
Delete a template with the given template ID
DELETE
/api/templates/{id}/
Deletes a template with the given template ID
POST
/api/v1/email-template/
{template_id}/clone
Create a clone of a template with the given template ID
POST
/api/templates/{id}/clone/
Create a clone of a template with the given template ID
Request specific fields using sparse fieldsets
POST
/api/v1/email-template/
{template_id}/render
Render the specified template with the provided data and return HTML and text versions of the email
This endpoint does not yet support our new template editor
POST
/api/templates/{id}/render/
Render a template with the given template ID and context attribute
Returns the HTML and plain text versions of the email template
Request specific fields using sparse fieldsets
POST
/api/v2/data-privacy/deletion-request
Request a deletion for the profiles corresponding to an email address, phone number, or person identifier (profile ID)
Note that only one identifier (email, phone_number, or person_id) can be specified
POST
/api/data-privacy-deletion-jobs/
Request a deletion for the profiles corresponding to one of the following identifiers: email, phone_number, or profile_id. If multiple identifiers are provided, we will return an error
New endpoints without corresponding v1/v2 endpoints
New endpoint
Supported features
Catalogs (all endpoints)
See API reference for details
Flows (all endpoints)
See API reference for details
Tags (all endpoints)
See API reference for details
GET /api/segments
Get all segments in an account
Filter to request a subset of all segments
Segments can be filtered by name, created, and updated fields
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET /api/segments/{id}/
Get a segment with the given segment ID
PATCH /api/segments/{id}/
Update the name of a segment with the given segment ID
GET /api/segments/{id}/relationships/{related_resource}/
Get all profile membership relationships for the given segment ID
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET /api/lists/{id}/relationships/{related_resource}/
Get profile membership relationships for a list with the given list ID
Returns a maximum of 10 results per page, which can be paginated with cursor-based pagination
GET /api/profiles/{id}/relationships/{related_resource}/
Get list membership or segment membership relationships for a profile with the given profile ID
GET /api/profiles/
Get all profiles in an account
Profiles can be sorted by the following fields, in ascending and descending order: id, created, email
Use filters to narrow your results. Request specific fields using sparse fieldsets
Returns a maximum of 20 profiles per page, which can be paginated with cursor-based pagination
GET /api/profiles/{profile_id}/lists/
Get list memberships for a profile with the given profile ID
GET /api/profiles/{profile_id}/segments/
Get segment memberships for a profile with the given profile ID
POST /api/profile-unsuppression-bulk-create-jobs/
Unsuppress one or more profiles
Only manually suppressed profiles will be unsuppressed and able to receive email marketing
Not supported for SMS marketing
GET api/metrics/{id}/
Get a metric with the given metric ID
Request specific fields using sparse fieldsets
GET /api/events/{id}/
Get an event with the given event ID
Request specific fields using sparse fieldsets
Include parameters can be provided to get the following related resource data: metrics, profiles
GET /api/events/{id}/metrics/
Get the metric for an event with the given event ID
Request specific fields using sparse fieldsets
GET /api/events/{id}/profiles/
Get all profiles associated with an event with the given event ID
GET /api/events/{id}/relationships/{related_resource}/
Get metrics or profile relationships for an event with the given event ID
GET /api/templates/{id}/
Get a template with the given template ID
Request specific fields using sparse fieldsets
