Profiles API Overview

The Profiles API is used for managing person records 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.

Libraries

We are working on adding the People 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

  • /api/v1/person/{PERSON_ID}
  • /api/v1/person/{PERSON_ID}/metrics/timeline
  • /api/v1/person/{PERSON_ID}/metric/{METRIC_ID}/timeline

Authentication

You authenticate to the People 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.

Retrieving a Person's Attributes

Retrieve all the data attributes for a person, based on the Klaviyo Person ID.

Arguments
No arguments.
Response

Returns a Person object. Any attributes that start with '$' are special Klaviyo attributes. With the exception od 'id' and 'object', any attributes that do no start with '$' are your custom-defined attributes.

GET https://a.klaviyo.com/api/v1/person/{{ PERSON_ID }} curl https://a.klaviyo.com/api/v1/person/dqQnNW -G \ -d api_key=API_KEY { "object": "person", "id": "dqQnNW", "$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": "", }

Adding or Updating a Person's Attributes

Add or update one more 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.

Arguments
In addition to these pre-defined Klaviyo arguments, you may pass any arbitrary key/value pair as a custom property. The names of the custom properties cannot start with $.
context
$id
your unique identifier for a person
$email
email address
$first_name
first name
$last_name
last name
$phone_number
phone number
$title
title at their business or organization
$organization
business or organization they belong to
$city
city they live in
$region
region or start they live in
$country
country they live in
$zip
postal code where they live
$image
url to a photo of the person
Response

Returns an updated Person object. Any attributes that start with $ are special Klaviyo attributes. With the exception of id and object, any attributes that do not start with $ are your custom properties.

PUT https://a.klaviyo.com/api/v1/person/{{ PERSON_ID }} curl https://a.klaviyo.com/api/v1/person/dqQnNW \ -X PUT \ -d api_key=API_KEY \ -d favorite_ice_cream=vanilla \ -d '$title="Ex-president"' { "object": "person", "id": "dqQnNW", "$email": "george.washington@example.com", "$first_name": "George", "$last_name": "Washington", "$organization": "U.S. Government", "$title": "Ex-president", "$city": "Mount Vernon", "$region": "Virginia", "$zip": "22121" "$country": "United States", "$timezone": "US/Eastern", "$phone_number": "", "favorite_ice_cream": "vanilla" }

Listing a person's complete event timeline

Returns a batched timeline of all events for a person.

Arguments
since
optional, string or integer
Either a Unix timestamp (UTC) to use as starting datetime, OR a UUID obtained from the next attribute of a prior API call. Defaults to current time.
count
optional, integer, defaults to 100
Number of events to return in a batch.
sort
optional, string, 'asc' or 'desc', defaults to 'desc'
Sort order to apply to timeline.
Response

A dictionary containing a list of metric event objects. Each event object contains information about what metric the event tracks, which person the event is related to, and any extra properties about the event. The next attribute should be passed as the since parameter to subsequent API calls to fetch the next batch of events.

GET https://a.klaviyo.com/api/v1/person/{{PERSON_ID}}/metrics/timeline curl https://a.klaviyo.com/api/v1/person/5ta2Hr/metrics/timeline -G \ -d api_key=API_KEY { "count": 1, "object": "$list", "data": [ { "object": "event", "id": "3EJ9cW", "person": { "id": "5ta2Hr", "$first_name": "George", "$last_name": "Washington", "$email": "george.washington@example.com", }, "event_name": "Placed Order", "statistic_id": "4Q8Y6N", "timestamp": "1400656845", "next": "31268980-edcb-11e3-8001-5b3d8e19a1ac", "event_properties": { "$extra": { "TotalTax": 0, "TotalDiscount": 0, "TotalShipping": 6, "Items": [ { "Description": null, "Price": 29, "Slug": "woodtooth", "Quantity": 1, "LineTotal": 29, "ProductID": "537c06c610bcf70400540c81", "Name": "Wooden Tooth" } ] }, "$value": 35, "IsDiscounted": false, "UsedCoupon": false } ] }

Listing a person's event timeline for a particular metric

Returns a person's batched timeline for one specific event type.

Arguments
since
optional, string or integer
Either a Unix timestamp (UTC) to use as starting datetime, OR a UUID obtained from the next attribute of a prior API call. Defaults to current time.
count
optional, integer, defaults to 100
Number of events to return in a batch.
sort
optional, string, 'asc' or 'desc', defaults to 'desc'
Sort order to apply to timeline.
Response

A dictionary containing a list of metric event objects. Each event object contains information about what metric the event tracks, which person the event is related to, and any extra properties about the event. The next attribute should be passed as the since parameter to subsequent API calls to fetch the next batch of events.

GET https://a.klaviyo.com/api/v1/person/{{PERSON_ID}}/metric/{{METRIC_ID}}/timeline curl https://a.klaviyo.com/api/v1/person/5ta2Hr/metric/4Q8Y6N/timeline -G \ -d api_key=API_KEY { "count": 1, "object": "$list", "data": [ { "object": "event", "id": "3EJ9cW", "person": { "id": "5ta2Hr", "$first_name": "George", "$last_name": "Washington", "$email": "george.washington@example.com", }, "event_name": "Placed Order", "statistic_id": "4Q8Y6N", "timestamp": "1400656845", "next": "31268980-edcb-11e3-8001-5b3d8e19a1ac", "event_properties": { "$extra": { "TotalTax": 0, "TotalDiscount": 0, "TotalShipping": 6, "Items": [ { "Description": null, "Price": 29, "Slug": "woodtooth", "Quantity": 1, "LineTotal": 29, "ProductID": "537c06c610bcf70400540c81", "Name": "Wooden Tooth" } ] }, "$value": 35, "IsDiscounted": false, "UsedCoupon": false } ] }