Server-Side API Overview

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.

Request and Response Formats

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 JSON object that has been base64 and URL encoded. 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 slight delay 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.

Track 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 by their phone number using a $phone_number key if you have SMS-only contacts). 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.

properties

optional, hash/dictionary or null

Custom information about this event. Any properties included here can be used for creating segments 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.

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 purchase)

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.

Identify API

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:

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 by their phone number using a $phone_number key if you have SMS-only contacts). 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.

Special Identify Properties

The Klaviyo CRM has a few built-in fields you can set with the Identify API. They are:

$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 state they live in

$country

country they live in

$zip

postal code where they live

$image

url to a photo of the person

$consent

type(s) of marketing the person consented to receive. This is only necessary for GDPR compliant businesses.