What's new with beta APIs

Learn about the major differences between Klaviyo’s V1/V2 APIs and our new APIs, currently in beta.

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

Enhancements to our current API functionality

The following is a list of the major differences between our old and new APIs:

  • 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:
    • /v1/metrics becomes /metrics , /events and /metrics-aggregates in the new APIs
    • /v2/list and /v2/group becomes /lists and /segments in the new APIs
      • All endpoints to modify subscription or suppression status, such as /v2/list/{list_id}/subscribe, will move to new /profile-subscription remote procedure call (RPC) methods
    • /v1/person and /v2/people become /profiles in the new APIs
  • There is now a distinct /client route to contain all endpoints designed to be used in client-side environments, while mirroring /api resource organization:
    • POST /api/track is now POST /client/events when called from a client (i.e. AJAX call)
      • When calling from server-side applications, use POST /api/events instead
    • POST /api/identify is now POST /client/profiles when called from a client (i.e. AJAX call)
      • When calling from server-side applications, use POST /api/profiles instead
    • POST /ajax/subscriptions is now POST /client/subscriptions when called from a client (i.e. AJAX call, form action)
      • When calling from server-side applications, use POST /api/subscriptions instead
  • 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

New endpoints covering more of our product

The new endpoints are as follows:

  • /segments
  • /catalog
  • /metrics
  • /flows
  • /tags (coming soon)
  • Dedicated subscriptions sub-resource under /profiles (coming soon), and dedicated endpoints for profile subscription and profile suppression actions

New features for existing endpoints

Some of our existing endpoints now have new features:

  • /profiles:
    • Easily list all profiles (with pagination)
    • Search and filter all profiles using standardized filter syntax
    • Custom profile properties are now part of the profile resource
    • List and segment membership now part of the profile resource
    • updated field included in profile resource
    • Include list and segment relationships in single query
  • /events (formerly /metric/timeline)
    • Improved and standardized timestamp filtering, sorting, and pagination behavior
    • Include metrics and profiles relationships in a single query
  • /lists and /segments
    • Dedicated /segments endpoint to list all segments in an account, and filter segments by name
    • Include full profiles in lists and segments in single query
    • Improved, standard relationship syntax used to add and delete profiles from lists
  • /campaigns (coming soon)
    • Send a campaign to multiple lists and segments
    • Associate tags with your campaign
    • Exclude lists and segments from campaign sends
    • Set UTM parameters with campaign sends

Did this page help you?