Learn about the differences between our v1/v2 APIs and our new APIs.
📘
We've updated our API versioning and deprecation policy
Review our updated API versioning and deprecation policy to learn about our date-versioned APIs, non-breaking and breaking changes, our API lifecycle, and more to effectively manage your API usage.
With Klaviyo’s new APIs, we’ve added improvements to our API functionality, new endpoints, and new features to some of our existing endpoints.
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.
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
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)
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
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
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
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
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
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
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 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.
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.
