The Server-Side API is composed of the Identify API and the Track API. These APIs are used for tracking people and the events or actions they do. For instance, tracking when someone is active on your website, when a purchase is made or when someone watches a video. They are optimized for low latency and high numbers of requests, so they do not adhere to the same REST principles our other APIs use.
If you are planning on a full ecommerce integration, please see this guide.
The Track and Identify APIs are most commonly accessed with our JavaScript library. Use our step-by-step guide to get started tracking people and events on your website.
Klaviyo also maintains API libraries in several languages:
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
The Server-Side APIs use the same request and response formats. Requests are made with a GET request to the specified endpoint with a single parameter, data, which is a base64 and JSON encoded string. The contents of the JSON dictionary or hash are different for each API, so the the documentation below will focus on that. If you're using one of our language libraries to send data, they automatically handle properly encoding data before making requests.
Responses from requests made to the Analytics APIs return either 1, for success, or 0, for failure. Keep in mind API requests are processed asynchronously, typically in less than a second, so when a request returns there might be a very seconds before data appears inside Klaviyo. In certain cases, such as pixel tracking, it may be better to return a blank pixel than a success or failure message. In those cases, you can always return a blank pixel by adding a GET parameter i=1 to your request.
Formatted as base64, JSON encoded strings.
For each example, we include what the dictionary or hash would look like and then what the base64, JSON encoded string looks like.
The main Events API endpoint is /api/track, which is used to track when someone takes an action or does something. It encodes the following data in a dictionary or hash:
$email key, or a unique identifier, using a $id. Other than that, you can include any data you want and it can then be used to create segments of people. For example, if you wanted to create a list of people on trial plans, include a person's plan type in this hash so you can use that information later.If you only want to track the first occurrance of an event and ignore subsequent events, you can use /api/track-once. It uses the same request format as /api/track.
{
"token" : "PUBLIC_API_KEY",
"event" : "Elected President",
"customer_properties" : {
"$email" : "thomas.jefferson@example.com"
},
"properties" : {
"PreviouslyVicePresident" : true,
"YearElected" : 1801,
"VicePresidents" : ["Aaron Burr", "George Clinton"]
},
"time" : 1529632847
}
curl https://a.klaviyo.com/api/track?data=eyJ0aW1lIjogMTUyOTYxODQ0NywgInRva2VuIjogIkFQSV9LRVkiLCAiY3VzdG9tZXJfcHJvcGVydGllcyI6IHsiJGVtYWlsIjogInRob21hcy5qZWZmZXJzb25AZXhhbXBsZS5jb20ifSwgInByb3BlcnRpZXMiOiB7IlllYXJFbGVjdGVkIjogMTgwMSwgIlByZXZpb3VzbHlWaWNlUHJlc2lkZW50IjogdHJ1ZSwgIlZpY2VQcmVzaWRlbnRzIjogWyJBYXJvbiBCdXJyIiwgIkdlb3JnZSBDbGludG9uIl19LCAiZXZlbnQiOiAiRWxlY3RlZCBQcmVzaWRlbnQifQ==
There are a few special properties you can optionally include when tracking an event. All of these belong in the "properties" dictionary. They are:
If you don't specify $event_id, it will default to the timestamp of the event. In practice, you should send an $event_id if you have an unique identifier for each event, for example an order ID.
You should also set the $event_id if you expect certain events to occur at the same point in time. This can happen when someone takes one action which you will split into multiple events. For example, if someone purchases multiple items and you want to record one event for each item purchased.
{
"token" : "PUBLIC_API_KEY",
"event" : "Louisiana Purchase",
"customer_properties" : {
"$email" : "thomas.jefferson@example.com"
},
"properties" : {
"$event_id" : 10001234,
"$value" : 11250000,
"From" : "France",
"SquareMiles" : 828000
},
"time" : 1529632847
}
curl https://a.klaviyo.com/api/track?data=eyJ0b2tlbiI6ICJBUElfS0VZIiwgImN1c3RvbWVyX3Byb3BlcnRpZXMiOiB7IiRlbWFpbCI6ICJ0aG9tYXMuamVmZmVyc29uQGV4YW1wbGUuY29tIn0sICJwcm9wZXJ0aWVzIjogeyIkdmFsdWUiOiAxMTI1MDAwMCwgIlNxdWFyZU1pbGVzIjogODI4MDAwLCAiRnJvbSI6ICJGcmFuY2UiLCAiJGV2ZW50X2lkIjogMTAwMDEyMzR9LCAiZXZlbnQiOiAiTG91aXNpYW5hIFB1cmNoYXNlIn0=
The Identify API endpoint is /api/identify, which is used to track properties about an individual without tracking an associated event. It encodes the following data in a dictionary or hash:
$email key, or a unique identifier, using a $id. Other than that, you can include any data you want and it can then be used to create segments of people. For example, if you wanted to create a list of people on trial plans, include a person's plan type in this hash so you can use that information later.{
"token" : "PUBLIC_API_KEY",
"properties" : {
"$email" : "thomas.jefferson@example.com",
"$first_name" : "Thomas",
"$last_name" : "Jefferson",
"Plan" : "Premium",
"SignUpDate" : "2016-05-01 10:10:00"
}
}
curl https://a.klaviyo.com/api/identify?data=eyJ0b2tlbiI6ICJBUElfS0VZIiwgInByb3BlcnRpZXMiOiB7IlNpZ25VcERhdGUiOiAiMjAxNi0wMS0yNyAxMjoxNzowNiIsICIkZW1haWwiOiAidGhvbWFzLmplZmZlcnNvbkBleGFtcGxlLmNvbSIsICIkbGFzdF9uYW1lIjogIkplZmZlcnNvbiIsICJQbGFuIjogIlRyaWFsIiwgIiRmaXJzdF9uYW1lIjogIlRob21hcyJ9fQ==
The Klaviyo CRM has a few built-in fields you can set with the Identify API. They are:
{
"token" : "PUBLIC_API_KEY",
"properties" : {
"$email" : "john.smith@example.com",
"$first_name" : "John",
"$last_name" : "Smith",
"$phone_number" : "1-617-555-1234",
"$title" : "Owner",
"$organization" : "Big Box Company"
}
}
curl https://a.klaviyo.com/api/identify?data=eyJ0b2tlbiI6ICJBUElfS0VZIiwgInByb3BlcnRpZXMiOiB7IiRvcmdhbml6YXRpb24iOiAiVW5pdGVkIFN0YXRlcyIsICIkZW1haWwiOiAiam9obi5hZGFtc0BleGFtcGxlLmNvbSIsICIkbGFzdF9uYW1lIjogIkFkYW1zIiwgIiRmaXJzdF9uYW1lIjogIkpvaG4iLCAiJHRpdGxlIjogIlByZXNpZGVudCIsICIkcGhvbmVfbnVtYmVyIjogIjEtNjE3LTU1NS0xMjM0In19