Track and Identify API Reference

read
Last updated at:

Overview

This is an overview of Klaviyo's Track and Identify 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. The Track and Identify API can be implemented via JavaScript or server side. Which implementation to use will depend on the specific use case, and most customers will use a mix of both.

Both APIs are optimized for low latency and high numbers of requests, so they do not adhere to the same REST principles our other APIs use. For more information review Klaviyo's REST API References.

If you are looking to integrate a custom ecommerce platform, review Klaviyo's guide to integrating a custom ecommerce cart or platform.

Responses

Responses from requests made to the Identify or Track APIs will return either 0 or 1. A 1 response means your data was received successfully and is queued for processing. A 0 response means your data did not decode to valid JSON and was not queued for processing. For logging purposes, we recommend logging any requests that result in a 0 response in case you need to verify the structure of the data being sent and resend it later.

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 rather 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.

Profiles and Unique Identifiers

The Identify method -- which allows you to identify and set properties on an individual -- allows you to identify any individual by including either their email address, with the $email key, or a unique identifier such as their user ID, with the $id key.

We highly recommend that you consistently identify all individuals using their email address only (with the $email key), and do not pass any $id values.

If you choose to use your own unique identifier with the $id key, you take on the full responsibility of identity management within your Klaviyo account. You must ensure that all calls are made mapping the right $id value you're setting to the right $email. If you send some calls with $id only, these profiles will exist without any associated $email. If calls then come in for the same person, but only $email is part of the request, a permanent duplicate profile will get created for the same person. Given the complexity of ensuring $id and $email are mapped correctly with every call across all data sources, we recommend exclusively using email address to identify individuals.

Note $id should never be used to track profiles anonymously. This will have a high potential of creating multitudes of profiles for individual people on your account if not set up thoughtfully. Only use $id if a given person has a known $email and their associated ID will never change (eg. an account ID in your own system).

The Klaviyo Web Tracking Snippet (Javascript)

Klaviyo's Web Tracking snippet loads our Javascript tracking library, allows form publishing, and enables the "Active on Site" event to track whenever a front-end event is tracked.

To get website activity tracking up and running, find your public API key by navigating to Account > Settings > API Keys. Your public key is six characters long. Add snippet of code below to your main store template so it's included on all pages. You should place this snippet either with other analytics scripts you use or right before the closing </body> tag.

You might be wondering, "How does using Klaviyo affect my site's performance?" The answer is Klaviyo doesn't affect your website's performance at all. Our code only loads once the rest of your website has finished loading. In addition, Klaviyo tells browsers to cache our JavaScript so your visitors often don't even need to download our JavaScript every time they switch pages.

This snippet automatically adds the _learnq object that can then be leveraged by any additional Identify or Track snippets you may want to add on the front-end.

Identify API

Our Identify API is used to send properties about a person to their profile in your account. The structure of the front-end and back-end versions of Identify API requests are similar but not exactly the same so make sure to verify that the request your setting up is using the format specific to the method with which you're sending it. They can be used interchangeably to send profile properties but you may opt for one over the other depending on when you want to send these properties and where the data source is for these properties.

The important difference in functionality to keep in mind when deciding which to use is that our front-end version of the Identify API will automatically cookie a browser which enables you to start also tracking events for that person on the front-end.

Identifying Users (Javascript)

The identify method allows you to identify and set properties on an individual. This method accepts a dictionary or hash of properties. When you identify someone, you must include either their email address, with the $email key, or a unique identifier such as their user ID, with the $id key. We highly recommend that you identify all individuals using their email address, with the $email key.

Once you've included at least one of those identifiers, you're free to add any custom properties you want. Custom properties are useful for tracking facts about individuals. In Klaviyo, you can then create segments of people based on those properties. For instance, you might want to track an individual's plan type or signup date. Klaviyo will also understand different data types you use, so feel free to use numbers, booleans, and dates.

If you are using Shopify Plus, change  customer  to  user. If you're using Shopify,  customer  is the correct object.

<script>
  var _learnq = _learnq || [];
  _learnq.push(['identify', {
    '$email': '{{ customer.email }}',
    '$first_name': '{{ customer.first_name }}',
    '$last_name': '{{ customer.last_name }}' 
  }]);
</script>

If visitors or customers can create accounts for your store, you can include an if statement here:

<script>
  var _learnq = _learnq || [];
  {% if customer.is_logged_in %}
  _learnq.push(['identify', {
    '$email': '{{ customer.email }}',
    '$first_name': '{{ customer.first_name }}',
    '$last_name': '{{ customer.last_name }}', 
  }]);
  {% endif %}
</script>

Depending on the types of templates you use for your website, the lines with the following code may use different syntax:

{% if customer.is_logged_in %}
{{ customer.email }}

Using the template language available, you want to check if the person viewing the current page is logged in. If so, you should output their email and name, if available. If you don't have name information, remove those two lines and the trailing comma after the email "$email" line.

In addition to properties you track, Klaviyo will automatically determine what website each person was first referred from for attribution tracking and a person's location based on where they access your website.

Klaviyo has a few default properties that are used to display information about people. For example, $first_name and $last_name.

Example Code:

<script>
  var _learnq = _learnq || [];

  // Identifying a person and tracking Klaviyo properties.
  _learnq.push(['identify', {
    '$email' : 'thomas.jefferson@gmail.com',
    '$first_name' : 'Thomas',
    '$last_name' : 'Jefferson'
  }]);

  // Adding custom properties. Note that Klaviyo understands different data types.
  _learnq.push(['identify', {
    'Plan' : 'Free Trial',
    'SignUpDate' : '2016-01-27 12:10:05',
    'HasFilledOutProfile' : false
  }]);
</script>

Identifying Users (Server Side)

The server side Identify API endpoint is https://a.klaviyo.com/api/identify, which is used to track properties about an individual without tracking an associated event. Requests are made with a GET request to the specified endpoint with a single parameter, data, which is a base64 encoded JSON string. The JSON object requires two arguments:

Argument Type Description
token (required) string Your public key (six characters long).
properties (required) hash/dictionary Custom information about the person. 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 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.

An Example JSON object:

{
  "token" : "API_KEY",
  "properties" : {
    "$email" : "thomas.jefferson@test.com",
    "$first_name" : "Thomas",
    "$last_name" : "Jefferson",
    "Plan" : "Premium",
    "SignUpDate" : "2016-05-01 10:10:00"
  }
}

Example request. Note: the string after data= is the base64 encoded and then URL encoded string of the JSON object above:

https://a.klaviyo.com/api/identify?data=ewogICJ0b2tlbiIgOiAiQVBJX0tFWSIsCiAgInByb3BlcnRpZXMiIDogewogICAgIiRlbWFpbCIgOiAidGhvbWFzLmplZmZlcnNvbkB0ZXN0LmNvbSIsCiAgICAiJGZpcnN0X25hbWUiIDogIlRob21hcyIsCiAgICAiJGxhc3RfbmFtZSIgOiAiSmVmZmVyc29uIiwKICAgICJQbGFuIiA6ICJQcmVtaXVtIiwKICAgICJTaWduVXBEYXRlIiA6ICIyMDE2LTA1LTAxIDEwOjEwOjAwIgogIH0KfQ==

Profile Properties

Klaviyo has a few default properties that are used to display information about people (designated with the $ character). These are:

  • $email: email address and the unique identifier for a profile
  • $id: optional unique identifier for a person (if used, this becomes the primary identifier instead of email. Please read the section at the top of this article before using $id)
  • $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
  • $address1: address line 1
  • $address2: address line 2
  • $city: city they live in
  • $region: region or state they live in
  • $country: country they live in
  • $zip: postal code where they live
  • $timezone: time zone
  • $latitude: latitude
  • $longitude: longitude
  • $source: where a contact came from

If you plan to use our SMS feature, the $phone_number must be passed in either the E.164 (e.g., +12345678910), RFC966 (e.g., +12-34-567-8910), or E.123 national (e.g., 12345678910) or international (e.g., +12 345 678 910) phone number formats.

Track API

Our Track API is used to send actions a person has taken to their profile in your account. The structure of the front-end and back-end versions of Track API requests are similar but not exactly the same so make sure to verify that the request your setting up is using the format specific to the method with which you're sending it. They can be used interchangeably to send events but you may opt for one over the other depending on when you want to send these events and where the data source is for these events.

The important difference in functionality to keep in mind when deciding which to use is that our front-end version of the Track API will only track events to a person's profile if that person is already cookied. The server-side version of this request requires a separate section called customer_properties which is used to designate to which profile this event should be tracked (using that person's email address as $email).

Tracking Events (Javascript)

You'll be using the _learnq object that's automatically added by the Klaviyo web tracking snippet.

To make an API call, Klaviyo uses a special syntax that allows your API calls to work even when our script hasn't loaded on the page yet. You'll create an array where the first value is the name of the method you want to call and any subsequent values are arguments to pass to that method.

The track method allows you to record events and actions people take on your website. This method accepts a string which is the name you give to that event. This method also accepts an optional dictionary or hash of properties associated with that event.

For example, you could track when someone purchases an item and include information on the purchase price and what items they bought. If you have an application where people have profiles you could track when someone fills out their profile.

When you add Klaviyo's web tracking snippet(s) to your site, we are only able to track the browsing activity of "known browsers" -- i.e. browsers that have visited and engaged at least once before. Klaviyo will not track anonymous browsers. More information can be found here.

Klaviyo's event tracking and analytics are very flexible, so you can customize them to keep track of what's important to your business. Our track method also understands different data types, so you can use numbers, booleans and dates and we'll create intelligent charts and graphs based on the data you send.

<script>
var _learnq = _learnq || [];
  _learnq.push(['track', 'Elected President', {
    'PreviouslyVicePresident' : true,
    'YearElected' : 1801,
    'VicePresidents' : ['Aaron Burr', 'George Clinton']
  }]);
</script>

Tracking Events (Server Side)

The Track API endpoint is https://a.klaviyo.com/api/track, which is used to track when someone takes an action or does something. Requests are made with a GET request to the specified endpoint with a single parameter, data which is a base64 encoded JSON string that is then URL encoded. The JSON object requires three arguments and allows for two optional arguments:

Argument Type Description
token (required) string Your public key (six characters long).
event (required) string Name of the event you want to track.
customer_properties (required) 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 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 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) integer When this event occurred. By default, Klaviyo assumes events happen when a request is made. If you'd like to track an event that happened in the past, use this property.

An Example JSON object:

{
  "token" : "API_KEY",
  "event" : "Elected President",
  "customer_properties" : {
    "$email" : "thomas.jefferson@test.com"
  },
  "properties" : {
    "PreviouslyVicePresident" : true,
    "YearElected" : 1801,
    "VicePresidents" : ["Aaron Burr", "George Clinton"]
  },
  "time" : 1500922636
}

Example request. Note: the string after data= is the base64 encoded and then URL encoded string of the JSON object above:

https://a.klaviyo.com/api/track?data=ewogICJ0b2tlbiIgOiAiQVBJX0tFWSIsCiAgImV2ZW50IiA6ICJFbGVjdGVkIFByZXNpZGVudCIsCiAgImN1c3RvbWVyX3Byb3BlcnRpZXMiIDogewogICAgIiRlbWFpbCIgOiAidGhvbWFzLmplZmZlcnNvbkB0ZXN0LmNvbSIKICB9LAogICJwcm9wZXJ0aWVzIiA6IHsKICAgICJQcmV2aW91c2x5VmljZVByZXNpZGVudCIgOiB0cnVlLAogICAgIlllYXJFbGVjdGVkIiA6IDE4MDEsCiAgICAiVmljZVByZXNpZGVudHMiIDogWyJBYXJvbiBCdXJyIiwgIkdlb3JnZSBDbGludG9uIl0KICB9LAogICJ0aW1lIiA6IDE1MDA5MjI2MzYKfQ==

If you only want to track the first occurrence of an event and ignore subsequent events, you can use /api/track-once. It uses the same request format as /api/track.

Event Klaviyo Properties

Klaviyo has a few default properties that are used to display information about an event (designated with the $ character). These are:

  • $event_id - a unique identifier for an event.  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.
  • $value - a numeric value to associate with this event (e.g. the dollar value of a purchase)
  • Klaviyo profile properties can be found above
x
Was this article helpful?
122 out of 223 found this helpful