Comparison between v1/v2 and new APIs

With Klaviyo’s new APIs, we’ve added improvements to our API functionality, new endpoints, and new features to some of our existing endpoints.

General improvements

All endpoints now follow the JSON:API standard
All endpoints have been rigorously vetted to ensure adherence to consistent URL, request, and response syntactical standards
The URL topology has been reorganized to promote strong-typing, clear resource separation, and consistency with the Klaviyo UI (see comparison chart)
There is a new versioning and deprecation policy
There are now explicitly-documented rate limits for all endpoints with standard, informative HTTP headers for retry control-flow

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 a maximum of 200 events per page, which can be paginated with 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 Profile fields can be nulled out by passing `null` into the associated profile field
POST /ajax/subscriptions	This endpoint was never publicly documented	POST /client/subscriptions	Create a new subscription for the given list ID and channel: Email is`email`, 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 Profile fields can be nulled out by passing `null` into the associated profile field
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/v1/person/{person_id}/ metric/{metric_id}/timeline	Returns a person's batched timeline for one specific event type.	GET /api/events?filter= equals(profile_id,PROFILE_ID), equals(metric_id,METRIC_ID)	Filter events using `profile_id` and `metric_id` to retrieve events for a specific metric for a given profile.
GET /api/v1/person/{person_id}/ metrics/timeline	Returns a batched timeline of all events for a person.	GET /api/events?filter= equals(profile_id,PROFILE_ID)	Filter events using `profile_id` to retrieve all the events for a given profile for all metrics.
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 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
DELETE /api/v2/list/{list_id}/ subscribe	Unsubscribe and remove profiles from a list	POST /api/profile-subscription-bulk- delete-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	DELETE /api/lists/{id}/relationships/ {related_resource}/	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/template-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/template-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
GET /api/v1/campaigns	Get all campaigns in an account Returns 0 to 100 results per page Offset pagination Results are sorted by descending `created_at` timestamp	GET /api/campaigns/	Get all campaigns in an account. Cursor-based pagination. Ability to specify sort order. Ability to filter by various attributes.
POST /api/v1/campaigns	Create a new campaign in draft mode.	POST /api/campaigns/	Creates a new campaign in draft mode. More granular send and tracking options.
GET /api/v1/campaign/ {campaign_id}	Get details for a specific campaign.	GET /api/campaigns/{id}/	Get details for a specific campaign.
PUT /api/v1/campaign/ {campaign_id}	Update details of a campaign. You can update a campaign's name, subject, from email address, from name, template or list.	PATCH /api/campaigns/{id}/	Update details of a campaign. Ability to configure more granular send and tracking options.
POST /api/v1/campaign/ {campaign_id}/send	Queues a campaign for immediate delivery.	POST /api/campaign-send- jobs/	Trigger a campaign to send asynchronously.
POST /api/v1/campaign/ {campaign_id}/schedule	Schedules a campaign for a time in the future.	POST /api/campaigns/	Creates a campaign given a set of parameters, then returns it.
POST /api/v1/campaign/ {campaign_id}/cancel	Cancels a campaign send. Marks a campaign as canceled.	PATCH /api/campaign-send- jobs/{id}/	Permanently cancel the campaign, setting the status to CANCELED or revert the campaign, setting the status back to DRAFT.
POST /api/v1/campaign/ {campaign_id}/clone	Creates a copy of a campaign. The new campaign starts as a draft.	POST /api/campaign-clone/	Clones an existing campaign, returning a new campaign based on the original with a new ID and name.
GET /api/v1/campaign/ {campaign_id}/recipients	Returns summary information about email recipients for the campaign specified that includes each recipient’s email, customer ID, and status.	GET /api/campaigns/ GET /api/segments/ {segment_id}/profiles/ GET /api/lists/{list_id}/profiles/	Returns some or all campaigns based on /v2 endpoint filters (`GET /api/campaigns`).
GET /api/v1/campaign/{campaign_id} GET /api/v1/email-templates/	Gets a campaign's info including its template id. Returns a list of all email templates which can be searched by template id.	GET /api/campaigns/{id}/campaign-messages/?include=template	Returns the messages for a given campaign including each message's template details.

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 minimum of 20 and a maximum of 100 profiles per page using the `page[size]` query parameter, 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-suppression-bulk-delete-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}/profile/	Get the profile 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
DELETE /api/campaigns/{id}/	Delete a campaign with the given campaign ID.
GET /api/campaign-messages/{id}/	Returns a specific message based on a required id.
PATCH /api/campaign-messages/{id}/	Update a campaign message.
GET /campaigns/{campaign_id}/tags/	Return all tags that belong to the given campaign.
GET /api/campaign-send-jobs/{id}/	Get a campaign send job.
GET /api/campaign-recipient-estimation-jobs/{id}/	Retrieve the status of a recipient estimation job triggered with the `Create Campaign Recipient Estimation Job` endpoint.
GET /api/campaign-recipient-estimations/{id}/	Get the estimated recipient count for a campaign with the provided campaign ID. You can refresh this count by using the `Create Campaign Recipient Estimation Job` endpoint.
POST /api/campaign-message-assign-template/	Creates a non-reusable version of the template and assigns it to the message.
POST /api/campaign-recipient-estimation-jobs/	Trigger an asynchronous job to update the estimated number of recipients for the given campaign ID. Use the `Get Campaign Recipient Estimation Job` endpoint to retrieve the status of this estimation job. Use the `Get Campaign Recipient Estimation` endpoint to retrieve the estimated recipient count for a given campaign.
GET /api/campaigns/{id}/relationships/{related_resource}/	If the `related_resource` is `tags`, returns the IDs of all tags associated with the given campaign.
POST /api/push-tokens/	Creates or updates a push token.