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.
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)
https://a.klaviyo.com
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.
To view your API key, you need to log in.
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.
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.
Retrieve all the data attributes for a person, based on the Klaviyo Person ID.
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": "",
}
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.
$.
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"
}
Returns a batched timeline of all events for a person.
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
}
]
}
Returns a person's batched timeline for one specific event type.
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
}
]
}