Identify API Reference

Hotjar’s Identify API allows you to pass data about your users to Hotjar using Javascript, saving them as User Attributes. These User Attributes can be used by Hotjar to enable advanced filtering and segmentation, giving you quality insights faster than before. You can send up to 100 user attributes on any site, with any number of users associated with those attributes. 

User Attributes can be used for filtering Recordings and targeting Surveys and Feedback widgets, as well as performing user lookup and deletion requests by User ID.

Follow the links below to learn more about User Attributes:

• Overview
• Handling User IDs
• Making calls to Identify
• User Attribute values
• Handling email addresses
• Examples of passing User Attributes to Hotjar
• Using the Identify API in a legally compliant manner
• Disabling User Attributes
• Deleting User Attributes
• Best practices
• FAQs

---

Overview

User Attributes are data values about users of your site passed to Hotjar from your client-side code over Hotjar's Identify API. This API is available on all pages containing the Hotjar Tracking Code.

This data is passed to Hotjar in key-value pairs as an asynchronous AJAX call to Hotjar's servers. These values are associated with a User ID, a uniquely identifiable value passed to Hotjar in your code from a User ID value from your user database. This allows Hotjar to associate data collected about them with the same user ID you use in your own database, as well as lookup user information held on Hotjar about that user.

There are 4 phases to the process of sending User Attributes to and using them with Hotjar. 

1. Get the data from your site.
2. Pass the data into Hotjar via the Identify API.
3. Hotjar stores the data about each user as User Attributes against their user_id.
4. You can now use Hotjar tools to target and filter by User Attributes.

Back to top

Making calls to Identify

Before you can begin making calls to Identify, User Attributes must be enabled in your Hotjar settings for each site you want to use User Attributes with. 

Enabling and disabling User Attributes

The ability to access the Identify API and User Attributes will be enabled by default if this feature is included in your Hotjar plan. However, if User Attributes were disabled in the past, you may need to re-enable them for use.

On your User Attributes page (Settings > User Attributes), find the Site you want to add User Attributes to using the selection drop-down. You'll see something like this showing the status of your User Attributes implementation:

You are also able to disable User Attributes on this page. Once you have selected a Site with User Attributes enabled, click Disable User Attributes. Once you have done this, further calls to the API will be blocked. The "Disable User Attributes" button will only appear after user attributes data has been received by Hotjar, but not before.

Any reports that rely on User Attributes for targeting purposes will be disabled, and you will not be able to re-enable them unless you change their targeting options, or re-enable User Attributes.

If you want to prevent User Attributes from being sent in the future, you should remove the Identify API code on your site. Once the code is deleted from your site, previously collected User Attributes will still exist, but they will no longer be updated or added to new users to your site.

The API call

Here is the format for a call to the Identify API:

hj('identify', userId, { 
    user_attribute: value
});

• The first parameter should always contain the string value "identify".
• The second should be a string containing the user id for a user on your site, from your own user database, or null if it is not known.
• The third is a series of key-value pairs inside an object. The key provides the User Attribute name, and the value defines both the type of a User Attribute and its value for that user.

The values passed into this call must come from your own site’s codebase. These values could be pulled directly from your servers or generated client-side. 

Once sent to Hotjar, these attributes and the values for each user are stored on Hotjar’s servers. Each time a call to Identify is made, the values stored on Hotjar’s servers will be replaced with the most recent values for these attributes.

You are able to look up all attributes sent to Hotjar in your User Attributes settings page. You can use the User Lookup feature to inspect what values have been passed for a specific user on your site.

As long as a user is identified during their session, Hotjar is then able to both associate User IDs and User Attributes with a session's Recording, and offer fine-grained Feedback widget targeting, allowing you to gather targeted feedback from specific users using Feedback and Surveys. For example: “I want this Survey to only target paying customers who made a purchase more than 10 days ago”.

Back to top

Handling User IDs

The second argument passed to Hotjar through the Identify API call should be a uniquely identifiable user ID from your own site's database. User Attributes are associated with this User ID.

The User ID should be unique per user but it should not itself contain personal information. It should also be a value that never changes for this user. Once you have set a User ID in Hotjar, it cannot be changed. If it changes, Hotjar will consider this to be a totally new user.

If a User ID is known, the user’s Hotjar ID will be associated with their User ID. A Hotjar ID is a randomly generated unique user ID, created at the Hotjar Site level. If a user does not have a User ID when they visit a site initially, then the Hotjar ID will be then associated with their User ID once the call to the Identify API with a User ID is made.

It’s helpful to work this through with an example.

Let's say we had a user, Rachel. She visits the site 3 times on 2 different devices.

• Session A - Rachel visits radbooks.com on her tablet.
  • She's not a user with the site yet and is assigned a Hotjar ID of 123
• Session B - Rachel then visits on her mobile.
  • She's not a user yet and is assigned a Hotjar ID of 456
• Session C - Rachel returns to the site from her mobile.
  • Hotjar recognizes her with the Hotjar ID of 456.
  • She then registers an account.
  • Your call to Identify assigns her a User ID of ABC, using the same User ID you have for her in your database.

Because we've associated her with a User ID on your site, we then connect all data associated with Hotjar ID 456 with her User ID of ABC, even though she wasn't logged in during Session B.

If Rachel then goes on to visit the site on her tablet in a 4th session, and this time logs in, Hotjar will then join together data from Session A on Session B, and C, giving you a full picture of her interactions with your site.

What if you don't have a User ID?

If the User ID is not known, then you must pass a value of null to the second parameter. When you do this any User Attributes passed to the Identify API will be associated with the user’s Hotjar ID instead. 

User Attribute values

You can pass the following values to a User Attribute key using the Identify API. Special characters cannot be used at this time.

Type	Values	Limitations/Notes
Number	Integers, or decimals	Minimum: -9007199254740991 Maximum: 9007199254740991
Strings	Text	200 characters maximum Case insensitive UTF-8 Supported Do not send email addresses
Date	ISO-8601 date strings	From JavaScript, use the toISOString() function on a date object.
Boolean	true or false values

Handling email addresses

At present, there is one User Attribute key for email addresses: email. Email addresses should be passed as strings to email. For example:

hj('identify', userId, {
	email: 'test@test.com' 
});

If any other User Attributes of a string type contain an email address, these will be rejected, meaning you should only use `email` to pass email addresses.

Examples of passing User Attributes to Hotjar

Identifying paying customers

Here is an example, where we want to be able to tell Hotjar how much money someone has spent on your site.

hj('identify', userId, {
	total_spend: 500
});

Multiple attributes can be passed by adding further key-value pairs into the object. Maybe you wanted Hotjar to know when they first became a customer?

hj('identify', userId, {      
	total_spend: 500,
	first_purchase: '2019-06-20Z'
});

Here we are telling Hotjar that your user became a customer to your service using an ISO8601 date string.

Identifying Attributes for Anonymous Users

Sometimes it’s useful to track information about users on your site, even if they aren’t yet users or paying customers. Let’s say you wanted to track the referral source, and landing page A-B test variant a potential lead reached you from:

hj('identify', null, {
    ab_test: 'variant-A',
    referrer: 'facebook_paid'
});

This would be useful if you wanted to target a Survey against users on variant-A, or only those who came to you from Facebook paid adverts, for example.

Using the Identify API in a Legally Compliant Manner

The Identify API is disabled by default, making it easy to avoid accidentally capturing personal information until you have handled privacy concerns appropriately.  By enabling User Attributes, you may be passing your end users’ personal data to Hotjar. We require that you acknowledge your legal obligations when doing so and accept Hotjar’s Data Processing Agreement.

It is your responsibility to use this feature in a legally compliant manner, consistent with the laws of your country and countries your users visit from. Visit our privacy page to learn more about Hotjar’s approach to user privacy. When using User Attributes, you should be aware of and conform to Hotjar’s Terms of Service and Acceptable Use Policy.

Back to top

Handling User Lookup and Deletion Requests

It is possible to lookup and delete a user's data using their User ID. Read more about this in our “How to Use User Lookup” article. It is important to note that if you know a user’s User ID and email address, you should look up their information with both. This is the only way to make sure that all personal information Hotjar has about this user has been looked up & deleted.

Back to top

Disabling User Attributes

To prevent further User Attributes being sent to Hotjar, you should disable User Attributes.

As long as User Attributes are enabled on your site, if you want to prevent them from being sent in the future, you should remove the code on your site sending them to Hotjar. Once the code is deleted from your site, previously collected User Attributes will still exist, though will no longer be updated or added to new users to your site.

Back to top

Deleting User Attributes

User Attributes can be deleted from the User Attributes management page by clicking on the trash can icon to the right of the attribute. Only team members with 'Read & Write' permissions or higher can delete User Attributes.

When an attribute is deleted, it will immediately disappear from the Hotjar application. However, the attribute is still stored in the back end for 7 days before being permanently deleted. Data associated with the attribute is ignored during the 7-day period. This is to prevent data from being sent due to caching issues.

If you wish to re-create an attribute that was deleted, you'll need to wait 7 days before the attribute can be re-created successfully.

Back to top

Best Practices

When to make API calls to Identify

You should make calls to Identify every time:

• A page is loaded with the most recent values (even if they haven’t changed).
• After a URL change in single-page apps.
• Every time a change is made. E.g. if you wanted to track their last purchase in a store, you would want to update this user attribute once a purchase has been made.

Each call will update the User Attributes with Hotjar with the most recent values. When a session Recording ends, the Recording saves the most recent values at the time the session ends.  When a call is made, but values have not been updated, the network request will not be sent in order to avoid unnecessary AJAX requests. 

Combining Identify API calls with triggers for targeting Surveys/Feedback widgets

If you plan on combining JavaScript triggers with User Attribute targeting for Surveys or Feedback widgets, you should ensure that the Identify call has happened before the trigger in your order of execution, bearing in mind any asynchronous calls to other services. If the trigger is executed before the Identify API call has finished execution, the Survey/Feedback widget will not show. 

Queuing calls to the API before Hotjar has loaded

If this script is added before your Hotjar tracking code, there will be an error.

The hj() object cannot be accessed until the Hotjar tracking code tag has executed. If for any reason you access the Identify API before the tracking code has executed you can add the following line of code before the API is called:

window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments)};

Testing User Attributes

There are a few ways you can test if User Attributes are being sent via the Identify API correctly.

• Once the code is live on your page and has been triggered at least once, you can visit your User Attributes settings page to see if the User Attribute captured by Hotjar is active on your page.
• You can enable Hotjar debug mode in your browser to see if Identify API calls are being sent to Hotjar successfully during your session.
• For null value users, you can use any email address you own to consent to connect Feedback responses through a Survey or Feedback. This will allow you to see which User Attributes are being passed to unidentified users, which is especially useful in checking you are not accidentally sending PII to Hotjar. It is important to note that users who have not consented to connect Feedback cannot be looked up in this way, so for testing purposes, you should set up a feedback widget to grant consent with your own email address.

Back to top