Identify API Reference

Getting insight from high volumes of data can be time-consuming without segmentation. Hotjar’s Identify API allows you to pass data about your visitors 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.

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

Table of Contents:

• 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
• Removing 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 visitor 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 visitor as User Attributes against their user_id.
4. You can now user Hotjar tools to target and filter by User Attributes.

Back to top

Making calls to Identify

Before you can begin making calls to Identify, you need to enable User Attributes in your Hotjar dashboard for each site you want to User Attributes within your account. 

Enabling and disabling User Attributes

The ability to access the Identify API and User Attributes will be disabled until you have enabled them in your User Attributes page.

On your User Attributes page (Settings > User Attributes), find the Site you want to add User Attributes to using the selection drop-down and click Enable User Attributes. 

You will be presented with a dialogue box asking you to confirm you have reviewed privacy considerations before enabling User Attributes, including agreeing to have signed a Data Processing Agreement with us.

Once enabled, calls to Identify will pass User Attribute data to Hotjar for this Site.

You are also able to disable User Attributes on this page. Once you have selected the Site with User Attributes enabled that you want to disable, click Disable User Attributes. Once you have done this, further calls to the API will be blocked.

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.

As long as User Attributes are enabled on your site, if you want to prevent them being sent in 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.

The API call

Here is the basic 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 visitor 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 Visitor 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 Incoming Feedback and Polls. For example: “I want this Poll 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 visitor 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 visitor’s Hotjar ID will be associated with their User ID. A Hotjar ID is uniquely generated based on a user’s device, location, and other information. 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 visitor’s Hotjar ID instead. 

User Attribute values

You can pass the following values to a User Attribute key using the Identify API.

Type	Values	Limitations/Notes
Number	Integers, or decimals	Minimum: -9223372036854775808 Maximum: 9223372036854775808
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 a basic 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 visitors 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 Poll 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 visitor's data using their User ID. Read more about this in our “How to Use Visitor 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 being sent in 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

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).
• 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. 

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 User Attributes are being sent via the Identify API correctly.

• Once the code is live on your page and been triggered at least once, you can visit your User Attributes settings page to see if the User Attribute is being captured by Hotjaris active on your page.
• For null value visitors, you can use any email address you own to consent to connect Feedback responses through a Poll or Incoming 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.

Using the Identify API with Google Tag Manager

There is a known issue with the Hotjar GTM tag, where GTM overrides the hj object required to access the Identify API. We recommend installing Hotjar as a custom tag.

Back to top

FAQs

User Attributes are being collected - now what can I do with them?

Once Hotjar is receiving User Attributes, you can use them for the following:

• Targeting Polls based on User Attributes
• Target Incoming Feedback based on User Attributes.

Why aren’t all my sessions from a specific user being captured?

Your users may be out of the sample. Read What happens when I exceed my plan’s limit? for more information. Alternatively, they may have chosen to opt-out of Hotjar. You can read more about cases where Hotjar does not track visitors in Does Hotjar collect data from ALL my visitors?

If you are being sampled, you can increase your plan to avoid sampling. Unfortunately, we cannot do anything about users who choose to block Hotjar!

I have sent Personally-Identifying Information about anonymous users (null value User IDs) to Hotjar

Don't do this.

No, seriously, do not do this!

If you have sent User Attributes to Hotjar on a null value, Hotjar has no way of attributing this information to a unique individual via Visitor Lookup unless they consent to connect feedback responses with their email address. This is not an effective way of making sure all users who you have collected personal information about can be retrieved and deleted.

Do not send PII as User Attributes unless you have a User ID. We cannot do anything to lookup and remove this data if you do it. You would need to delete the Site in Hotjar.

I am a V1 billing customer. How do I gain access to the Identify API?

The Identify API and User Attributes are unavailable if you are on a V1 plan. You cannot use them without upgrading to V2 billing or higher.

Contact Support, who will advise you on how to upgrade your billing version.

Back to top