Getting started with Track and Identify APIs

You can use the Track and Identify APIs to track when someone is active on your website, when a purchase is made, or when someone watches a video. These APIs can be implemented on the front-end (via JavaScript on a site) or the back-end (on the Klaviyo server-side). The implementation to use will depend on the specific use case, and most customers 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're looking to integrate an ecommerce platform not currently supported by one of Klaviyo’s pre-built integrations or partner integrations, or you’ve built your own custom cart solution, check out our guide Integrate a platform without a pre-built Klaviyo integration.

Responses

Responses from requests made to the Track or Identify API will return either 1 or 0.

📘

Info

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.

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.

Track API

Read more about the Track API in our API reference documentation.

Klaviyo's main onsite tracking snippet, known as "klaviyo.js", 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 onsite tracking up and running, you’ll need to add the code snippet below to your main store template. Place the code snippet either with any other analytics scripts you use or right before the closing </body> tag. Replace the “Public API Key” text with your public API key. To find your public API key, navigate to Account > Settings > API Keys. Your public key is six characters long.

<script type="application/javascript" async src="https://static.klaviyo.com/onsite/js/klaviyo.js?company_id=Public API Key"></script>

This script runs asynchronously and can be added to your site without affecting performance. For more information, see our article on Klaviyo.js and site speed reports. The script is also cached in a user’s browser, so they won’t need to download it 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

Read more about the Identify API in our API reference documentation.

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 (using the $email key) or a unique identifier such as their user ID (using the $id key).

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

If you choose to use a unique identifier via the $id key, you will be responsible for identity management within your Klaviyo account. You must ensure every call you make maps the correct $id to the associated $email. Calls sent with only an $id value will cause Klaviyo to create profiles without an associated $email. If a call then comes in for the same person, but only identifies them via their $email, a permanent duplicate profile will be created for the same person.

As of April 2022, external id ($id) property has a limit of 64 characters. Any characters over the limit will be truncated.

📘

Info

The $id key should never be used to track profiles anonymously, as this has a high potential of creating multiple profiles for individuals in 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).