Analytics API Overview

The Analytics API is composed of the People API and the Events 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.

Libraries

The Events and People 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)

API Endpoint

https://a.klaviyo.com

Summary of Resource URL Patterns

  • /api/track
  • /api/track-once
  • /api/identify

Request and Response Formats

The Analytics 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 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.

Requests

Formatted as base64, JSON encoded strings.

Responses

  • 1 Success
  • 0 Failure

About Examples

For each example, we include what the dictionary or hash would look like and then what the base64, JSON encoded string looks like.

Events API

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:

token
string
This is your public API key.
event
string
Name of the event you want to track.
customer_properties
hash/dictionary
Custom information about the person who did this event. You must identify the person by their email, using a $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 dynamic lists 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.
properties
optional, hash/dictionary or null
Custom information about this event. Any properties included here can be used for segmentations and creating dynamic lists later For example, if you track an event called "Posted Item," you could include a property for item type (e.g. image, article, etc.).
time
optional, UNIX timestamp or null
When this event occurred. By default, Klaviyo assumes events happen when a request is made. If you'd like to track and event that happened in past, use this property.

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" : "Purchased Items", "customer_properties" : { "$email" : "george.washington@example.com" }, "properties" : { "Total Price": 24.99, "Items Purchased": ["Cheerios", "Milk", "Cereal Bowls"] }, "time" : 1397892137 } curl https://a.klaviyo.com/api/track?data=eyJ0aW1lIjogMTM5Nzg3NzczNywgInRva2VuIjogIkFQSV9LRVkiLCAiY3VzdG9tZXJfcHJvcGVydGllcyI6IHsiJGVtYWlsIjogImdlb3JnZS53YXNoaW5ndG9uQGV4YW1wbGUuY29tIn0sICJwcm9wZXJ0aWVzIjogeyJJdGVtcyBQdXJjaGFzZWQiOiBbIkNoZWVyaW9zIiwgIk1pbGsiLCAiQ2VyZWFsIEJvd2xzIl0sICJUb3RhbCBQcmljZSI6IDI0Ljk5fSwgImV2ZW50IjogIlB1cmNoYXNlZCBJdGVtcyJ9

Special Event Properties

There are a few special properties you can optionally include when tracking an event. All of these belong in the "properties" dictionary. They are:

$event_id
an unique identifier for an event
$value
a numeric value to associate with this event (e.g. the dollar value of a purcahse)

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" : "Purchased Items", "customer_properties" : { "$email" : "george.washington@example.com" }, "properties" : { "$event_id" : 10001234, "$value": 24.99, "Items Purchased": ["Cheerios", "Milk", "Cereal Bowls"] }, "time" : 1397892137 } curl https://a.klaviyo.com/api/track?data=eyJ0aW1lIjogMTM5Nzg3NzczNywgInRva2VuIjogIkFQSV9LRVkiLCAiY3VzdG9tZXJfcHJvcGVydGllcyI6IHsiJGVtYWlsIjogImdlb3JnZS53YXNoaW5ndG9uQGV4YW1wbGUuY29tIn0sICJwcm9wZXJ0aWVzIjogeyJJdGVtcyBQdXJjaGFzZWQiOiBbIkNoZWVyaW9zIiwgIk1pbGsiLCAiQ2VyZWFsIEJvd2xzIl0sICJUb3RhbCBQcmljZSI6IDI0Ljk5fSwgImV2ZW50IjogIlB1cmNoYXNlZCBJdGVtcyJ9

People API

The main People 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:

token
string
This is your public API key.
properties
hash/dictionary
Custom information about the person who did this event. You must identify the person by their email, using a $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 dynamic lists 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" : "Trial", "Sign Up Date" : "2013-01-27 12:17:06" } } curl https://a.klaviyo.com/api/identify?data=eyJ0b2tlbiI6ICJBUElfS0VZIiwgInByb3BlcnRpZXMiOiB7IiRlbWFpbCI6ICJ0aG9tYXMuamVmZmVyc29uQGV4YW1wbGUuY29tIiwgIiRsYXN0X25hbWUiOiAiSmVmZmVyc29uIiwgIlBsYW4iOiAiVHJpYWwiLCAiU2lnbiBVcCBEYXRlIjogIjIwMTMtMDEtMjcgMTI6MTc6MDYiLCAiJGZpcnN0X25hbWUiOiAiVGhvbWFzIn19

Special People Properties

There are a few special properties when you identify someone that are used when displaying individual profiles so Klaviyo be used as a CRM. They are:

$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
{ "token" : "PUBLIC_API_KEY", "properties" : { "$email" : "john.adams@example.com", "$first_name" : "John", "$last_name" : "Adams", "$phone_number" : "1-617-555-1234", "$title" : "President", "$organization" : "United States" } } curl https://a.klaviyo.com/api/track?data=eyJ0b2tlbiI6ICJBUElfS0VZIiwgInByb3BlcnRpZXMiOiB7IiRvcmdhbml6YXRpb24iOiAiVW5pdGVkIFN0YXRlcyIsICIkZW1haWwiOiAiam9obi5hZGFtc0BleGFtcGxlLmNvbSIsICIkbGFzdF9uYW1lIjogIkFkYW1zIiwgIiRmaXJzdF9uYW1lIjogIkpvaG4iLCAiJHRpdGxlIjogIlByZXNpZGVudCIsICIkcGhvbmVfbnVtYmVyIjogIjEtNjE3LTU1NS0xMjM0In19