Identify API reference

📘

Info

This article assumes you’ve set up your site according to our Getting started with Track and Identify APIs article.

There are two versions of our Identify API: a front-end and a back-end. The structures are similar, but not exactly the same, so you may opt for one over the other depending on when you want to send properties back to Klaviyo and what 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 Identify API automatically cookies a user’s browser, which enables you to also start tracking events for that user on the front-end.

Front-end identifying events (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 one of the following:

• Highly recommended: an email address ($email), or if you have SMS-contacts, a phone number ($phone_number)
• A unique identifier, such as their user ID ($id)

📘

Info

We highly recommend you consistently identify all individuals using only their email address ($email), and do not pass $id values. For more information, see Getting started with Track and Identify APIs

Once you've included at least one of those identifiers, you're free to add any custom properties you want, such as an individual’s plan type or their signup date. Klaviyo understands different data types, so feel free to use numbers, booleans, dates, and lists. These custom properties are useful for tracking facts about individuals, which can then be used to create segments of people in Klaviyo.

📘

Info

While you can pass lists of dates or booleans into Klaviyo, you won’t be able to use those data types everywhere. Email templates can handle the different data types, but you won’t be able to create filters or flows; instead, each entry in the list will be treated as a string. This limits the operations you can do to things like “contains” comparisons (e.g., “listProperty contains '2021-09-21 00:00:00'"), so long as it’s a text comparison (you wouldn’t be able to filter based on the comparison “list contains a value greater than 5”).

Script examples

Basic identify script

Use the following script to add the basic Identify API to your site:

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

Track accounts

If customers can create accounts for your store, you can include an if statement in the template language to check if the customer is logged in:

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

{% if customer.is_logged_in %}
[email protected]
First_name
Last_name

If the customer is logged in, output their email and name (if available). If you don’t have their email and name, remove the references to first name and last name.

In addition to properties you track, Klaviyo will automatically determine the following information about each customer:

• The website someone was first referred from for attribution tracking
• A person's location, based on where they access your website; if there is no other data associated with the person (e.g., email open, purchase with billing location), this will be based on their IP location

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

Example Code:

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

  // Identifying a person and tracking Klaviyo properties.
  _learnq.push(['identify', {
    '$email' : '[email protected]',
    '$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>

Back-end identifying users (server side)

The Identify API endpoint is https://a.klaviyo.com/api/identify, which is used to track a customer’s properties. There are two ways to make requests of the back-end Identify API: GET and POST.

GET

❗️Warning
This is offered for backwards compatibility; we recommend all new implementations use the POST approach below.

GET requests to this endpoint are useful to identify a profile and update its properties without an associated event. They’re made via the data parameter, which is a base64-encoded JSON string that is then URL encoded and passed as a query parameter. The JSON object requires two arguments, as described in the table below:

GET example JSON object

{
  "token" : "API_KEY",
  "properties" : {
    "$email" : "[email protected]",
    "$first_name" : "Thomas",
    "$last_name" : "Jefferson",
    "Plan" : "Premium",
    "SignUpDate" : "2016-05-01 10:10:00"
  }
}

Example request

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==

POST

POST requests are sent via the data JSON object, serialized as a URL-encoded form, and are used to track and update properties about an individual without tracking an associated event. This endpoint can accept payloads up to approximately 1MB and can handle up to 200 unique metrics (event types). The JSON object requires one argument and allows for one optional argument, as described in the table below:

POST example JSON object

{
    "token": "PUBLIC_KEY",
    "properties": {
      "$email": "[email protected]",
      "$first_name": "Abraham",
      "$last_name": "Lincoln",
      "$city": "Springfield",
      "$region": "Illinois"
    }
}

Specific properties

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

📘

Info

Properties related to someone’s location (e.g., $city, $region, $country, and $zip) are automatically updated using their IP address or billing information. If you manually make changes to this information, it can be overwritten during a sync.

If you plan to use our SMS features, the $phone_number must be passed in one of the following phone number formats:

• National:
  • E.123; e.g., 12345678910
  • E.164; e.g., +12345678910
  • RFC966; e.g., +12-34-567-8910
• International; e.g., +12 345 678 910

Additional resources

• Getting started with Track and Identify APIs
• Track API reference