Hotjar API Reference

• Overview
• Authentication
• Rate limits
• Responses and errors
• Pagination
• Versioning

API Reference

• Survey Responses
• User Lookup

---

Overview

The Hotjar API is a JSON based HTTP API:

• It is resource-oriented (like REST)
• It accepts JSON request bodies
• It returns JSON responses
• Uses standard HTTP verbs (methods)
• Uses HTTP status codes to communicate status
• Uses the OAuth client credentials flow for authentication

All API calls are made to the same base domain: https://api.hotjar.io

Authentication

The Hotjar API uses a combination of API keys and the OAuth client credentials flow for authentication. You can generate an API key from within the Hotjar app. API keys are made up of a pair of items: the client ID and the client secret. When you want to use the API you must:

• Send a request to the token endpoint with the client ID and client secret
• Receive in response a temporary bearer token
• Send the bearer token with all other API calls via the Authorization HTTP Header

The API keys grant access to many privileges, so you must keep them secret. Do not share them in publicly accessible areas such as Gitlab or embedded in an application. The API keys are intended for machine-to-machine communication, where the API key is kept secret.

Getting the bearer token

To obtain an access token, you must send an HTTP POST request to /v1/oauth/token. The request must be encoded as application/x-www-form-urlencoded (this is an OAuth requirement) and must include three parameters:

1. grant_type must be set to client_credentials
2. client_id must be set to your API key's client ID
3. client_secret must be set to your API key's client secret

Here is a simplified example:

POST /v1/oauth/token HTTP/1.1
Host: api.hotjar.io

grant_type=client_credentials
&client_id=xxxxxxxxxx
&client_secret=xxxxxxxxxx

The response, if successful, is a JSON object response containing three keys:

1. token_type which will be set to Bearer
2. expires_in which specifies the number of seconds until the bearer token expires
3. access_token which is the bearer token itself

Here is an example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
"access_token":"<token>",
"token_type":"Bearer",
"expires_in":3600,
}

Using the bearer token

You must send the bearer token, obtained via the method above, via the Authorization HTTP header when making API calls. The header's value should be Bearer <token here>. Here is a simplified example:

GET /v1/sites/1/surveys HTTP/1.1
Host: api.hotjar.io
Authorization: Bearer token_goes_here

In the event that your requests don't include the header then it will respond with an HTTP status code of 401. If the token is invalid, or your API key doesn't have permission to undertake the requested action, then it will respond with an HTTP status code of 403. 

Back to top

Rate Limiting

Currently, the Hotjar API is rate limited by source address and is only limited to 3000 requests per minute (50 per second). We intend to evaluate further rate-limiting restrictions in the future. If you make too many requests, the API will respond with an HTTP status code of 429. 

Back to top

Responses and Errors

The HTTP status code is authoritative; if the status code is in the 2XX range then the API call was a success, if the status code is in the 4XX range then there was a client error, and if the status code is in the 5XX range then there was a server error.

If the API endpoint returns data, then it will be returned as JSON. In these cases, the top-level response will be a JSON object (rather than an array). If the endpoint returns multiple objects (rows), they will be sent as an array under a results key. A top-level next_cursor key will be included in the response for endpoints with pagination (see below).

In some cases, when an error is returned, additional information about the error will be included. In these cases, the response will be JSON encoded and will include the following fields:

• code - a string intended to be machine-readable, containing the error code
• msg - a string, human-readable, explaining the cause of the error.

Back to top

Pagination

The Hotjar API utilizes cursor-based pagination. When an endpoint supports pagination, you can send a limit parameter to specify how many items you want to receive. When you make the first request, you'll receive in the response a next_cursor field. To get the next page of items when you make the next request pass the value of next_cursor as a parameter called cursor. The API then uses this value to return the next page of items. When there are no additional results, next_cursor is null.

Back to top

Versioning

The Hotjar API uses a "global" version number rather than each individual endpoint being versioned. We will not introduce backwards incompatible changes within a version. At present, we only have one API version (v1) and may introduce other versions in the future. We will ensure that if, in the future, we decide to stop supporting a version of the API, we will give at least six months' notice before removing support.

Back to top

API Reference

Survey Responses

List Surveys

GET /v1/sites/:site_id/surveys

• site_id: The site's unique identifier. This ID can be found in the Sites & Organizations page under the respective organization.

URL Parameters (optional):

• limit: The number of surveys to be returned in the response. Maximum 100.
• cursor: The cursor to be used for fetching a specific page. 
• with_questions: Flag (true/false) indicating whether the question information should be included in the response. By default, it is not included.

Response fields:

• results: A list of Survey items. Each Survey contains the following fields:
  • id (string): The survey's unique identifier.
  • url (string): The survey's URL for the Hotjar API.
  • created_time (datetime): The survey's time of creation in rfc3339 format.
  • updated_time (datetime): The survey's time of creation in rfc3339 format.
  • is_enabled (boolean): Flag indicating whether the survey is enabled or not.
  • name (string): The survey's name.
  • responses_url (string): The Hotjar API URL for the responses of this survey
  • type (string): The type of the survey. It can be one of link, full_screen, or popover.
  • questions: A list of Question items. Included optionally if the flag is set to true in the request parameters.
    • id (string): The question's unique identifier.
    • is_required (boolean): Flag indicating whether the question is required.
    • text (string): The text of the question.
    • type (string): The type of the question. Possible values are reaction,long-text, short-text, single-option, multiple-option email, rating-1-5, rating-1-7, nps, statement, and  thank-you.
    • image_url (Optional url): The image URL associated with the question, if there is one.
    • choices (Optional list of Choice objects): The possible choices that the users can select. This field will be used only for single-option or multiple-option question types.
      • text (string): The text of the choice
      • allow_comment (boolean): Flag indicating whether users can comment if they select this choice.
    • labels (Optional Label object): Information about the naming of the low label and high label. This field will only be used for rating-1-5, rating-1-7, nps, and reaction question types.
      • low_label (string): The naming for the lowest score option for the question.
      • high_label (string): The naming for the highest score option for the question.
  • sentiment_analysis_enabled (boolean): Indicates whether responses go through sentiment analysis or not.
• next_cursor (string): The cursor for the next page.

Sample response:

{
  "next_cursor": "gAAAAABj90lFO37F7V3M0GLNa-cp0QIqq91P3faMKqptoVZpRGn8LH9lufXhTX2MOtv566sVsbVz_YGS9FYp_N19DNK8brCAhEbIFKcgYUjh6vX2FjRgtoELfj9E3_kggNZ5DF8Ul3oE",
  "results": [
    {
      "created_time": "2023-02-23T11:08:53.287Z",
      "id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
      "is_enabled": false,
      "name": "My survey name",
      "responses_url": "/v1/sites/12345/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
      "type": "popover",
      "url": "/v1/sites/12345/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
      "questions": [
        {
          "choices": null,
          "id": "question_f5937a53-674a-43d1-b4b7-ada420568ebf_7b725dac",
          "image_url": null,
          "is_required": true,
          "labels": null,
          "text": "What do you think about our API?",
          "type": "long-text"
        }
      ],
      "sentiment_analysis_enabled": false
    }
  ]
}

Fetch Survey

GET /v1/sites/:site_id/surveys/:survey_id

• site_id: The site's unique identifier. This ID can be found in the Sites & Organizations page under the respective organization.
• survey_id: The survey's unique identifier.

Response fields:

Response fields are the same as the Survey item described in the List Surveys endpoint above. The questions are always included in this endpoint.

Sample response:

{
  "created_time": "2023-02-23T11:08:53.287Z",
  "id": "survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
  "is_enabled": false,
  "name": "My survey name",
  "responses_url": "/v1/sites/123456/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf/responses",
  "type": "popover",
  "url": "/v1/sites/123456/surveys/survey_f5937a53-674a-43d1-b4b7-ada420568ebf",
  "questions": [
    {
      "choices": null,
      "id": "question_f5937a53-674a-43d1-b4b7-ada420568ebf_7b725dac",
      "image_url": null,
      "is_required": true,
      "labels": null,
      "text": "What do you think about our API?",
      "type": "long-text"
    }
  ],
  "sentiment_analysis_enabled": true
}

List Survey Responses

GET /v1/sites/:site_id/surveys/:survey_id/responses

• site_id: The site's unique identifier. This ID can be found in the Sites & Organizations page under the respective organization.
• survey_id: The survey's unique identifier.

URL Parameters (optional):

• limit: The number of survey responses to be returned in the response. Maximum 100.
• cursor: The cursor to be used for fetching a specific page.

Response fields:

• results: A list of Survey Response items. Each Survey Response contains the following fields:
  • id (string): The response unique identifier.
  • answers (list of Survey Answer objects). Each Survey Answer contains the following fields:
    • question_id (string): The question's identifier
    • answer (string): The answer.
    • comment (string): Optional comment provided by the user.
    • tags (list of Survey Response Tag objects). Each Survey Response Tag contains the following fields:
      • name (string): The name of the tag.
    • sentiment (string): The sentiment of the answer text. It can be one of "positive", "negative", "neutral", or `null`. The null value is set for non-text answers or when no sentiment was set. The sentiment key will only be present when it is part of your Ask product plan.
      
  • browser (string): The browser on which the response was captured.
  • country (string): 2-letter code of the user's country. The country code list can be found here https://www.iso.org/iso-3166-country-codes.html
  • created_time (datetime): The response's time of submission in rfc3339 format.
  • device (string): The device type used to submit the response. It can be any of "tablet", "mobile", "desktop"
  • hotjar_user_id (string): A unique identifier for the user that submitted the response
  • is_complete (boolean): Flag indicating whether the response is completed or not.
  • os (string): The user's operating system.
  • recording_url (string): A link to the Hotjar Recording that contains that response, if it exists.
  • response_origin_url (string): The URL of the site where the user submitted the response.
  • user_attributes (list of User Attribute): A list of user's attributes as provided by the Hotjar Identify API. Each User Attribute contains the following fields:
    • name (string): The name of the user attribute
    • value (string/integer/float/boolean/datetime): The value of the user attribute
  • window_size: The window size of the user's browser. It contains the following fields:
    • width (integer): The width of the window, if it exists.
    • height (integer): The height of the window, if it exists.
• next_cursor (string): The cursor for the next page.

Sample response:

{
  "next_cursor": "gAAAAABj91CIjMAhTxEHLEyeycuAsTylGzwlaKMIo5lBl_zKikJeO3DQa9hvsChE2Kc032DlDne0HE7xURLuyFTDWWaiBZoob0wCLhb39eCotgBKNW5vodsXEVIrNT0nX_X5kdziNDup",
  "results": [
    {
      "answers": [
        {
          "answer": "I love your product.",
          "comment": "I use it everyday.",
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
          "tags": [
            {
              "name": "todo"
            },
            {
              "name": "positive"
            }
          ],
          "sentiment": "positive"
        },
        {
          "answer": "10",
          "comment": null,
          "question_id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
          "tags": [],
          "sentiment": null
        }
      ],
      "browser": "Mobile Safari UI/WKWebView",
      "country": "mt",
      "created_time": "2023-02-23T11:39:51.473Z",
      "device": "desktop",
      "hotjar_user_id": "8c9edf6f-ff84-3f2b-9755-15bbfff75aaf",
      "id": "response_f8ccb724-8110-48d0-8715-2138be7a9c06",
      "is_complete": false,
      "os": "iOS",
      "recording_url": null,
      "response_origin_url": "https://www.example.com/484845acc8164763ba6d",
      "user_attributes": [
        {
          "name": "customer_type",
          "value": "enterprise"
        }
      ],
      "window_size": {
        "height": 768,
        "width": 1024
      }
    }
  ]
}

Example payload for different Survey Question types:

reaction

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efca",
  "type": "reaction",
  "text": "How would you rate your experience?",
  "is_required": true,
  "labels": {
    "low_label": "Not good at all",
    "high_label": "Excellent!"
  }
}

short-text

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcb",
  "type": "short-text",
  "text": "Do you like our new layout?",
  "is_required": true
}

long-text

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcc",
  "type": "long-text",
  "text": "What do you like in the new layout?",
  "is_required": false
}

single-option

{
    "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efcd",
    "type": "single-option",
    "text": "Would you use our site again?",
    "is_required": true,
    "choices": [
      {
        "text": "Yes",
        "allow_comment": false
      },
      {
        "text": "No",
        "allow_comment": false
      },
      {
        "text": "I don't know",
        "allow_comment": false
      }
    ]
  }

multiple-option

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203efde",
  "type": "multiple-option",
  "text": "Tell us what you like more",
  "is_required": false,
  "choices": [
    {"text": "The User Experience", "allow_comment": false},
    {"text": "The features", "allow_comment": false},
    {"text": "Other", "allow_comment": true}
  ]
}

rating-1-5

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef08",
  "type": "rating-1-5",
  "text": "From 1 to 5 how much do you like our service?",
  "is_required": true,
  "labels": {"low_label": "I hate it", "high_label": "I love it"}
}

rating-1-7

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef09",
  "type": "rating-1-7",
  "text": "Rate your experience from 1 to 7.",
  "is_required": false,
  "labels": {"low_label": "Worst experience ever.", "high_label": "Amazing!"}
}

nps

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef10",
  "type": "nps",
  "text": "How likely are you to recommend us to a friend or colleague?",
  "is_required": true,
  "labels": {"low_label": "Not likely at all.", "high_label": "Absolutely!"}
}

email

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef11",
  "type": "email",
  "text": "Please enter your email address in case you want us to contact you",
  "is_required": false
}

thank-you

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef12",
  "type": "thank-you",
  "text": "Thank you very much for your responses!",
  "is_required": true
}

statement

{
  "id": "question_8ec93bfa-1538-4240-bcdd-3daddb1c6627_4203ef13",
  "type": "statement",
  "text": "This Survey will take you 5 minutes",
  "is_required": true
}

 

User Lookup

Perform a user lookup (with optional deletion)

POST /v1/organizations/:organization_id/user-lookup

• organization_id: The organization's unique identifier. This ID can be found in the Sites & Organizations page next to the respective organization.

JSON Body Parameters:

Requests to this endpoint must be sent with Content-Type: application/json; charset=utf-8.

• data_subject_email: String email address of the target user.
• data_subject_site_id_to_user_id_map: A map (object) of <site_id> to <user_id_on_your_site> entries, useful when you have used the User Attributes API to send the user's unique ID to us.
• delete_all_hits: Boolean (true/false) indicating whether any found data should be immediately deleted.

For a successful request, at least one (or both) of data_subject_email and data_subject_site_id_to_user_id_map must be sent in the body of your request.

If delete_all_hits is false, meaning that we will not automatically delete all the hits, then an email with a link to the data report will be sent to the data_subject_email address and the default recipient address that you specify in the User Lookup page. This mimics the way the User Lookup tool works through the web application.

If delete_all_hits is true then no email will be sent to you or the data subject. We will silently delete any data we find.

Sample request:

## User Lookup
curl -X "POST" "https://api.hotjar.io/v1/organizations//user-lookup" \
-H 'Authorization: Bearer ' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"delete_all_hits": false,
"data_subject_email": "text@example.com",
"data_subject_site_id_to_user_id_map": {
"42": "unique_id_42"
}
}'

Sample response:

202 Accepted, with no data.

Back to top