> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotjar as a data source

> Bring Hotjar surveys, survey questions, survey responses and their answers to Nekt.

Hotjar (by Contentsquare) is a product experience tool that collects website feedback through surveys, heatmaps and session recordings. This connector reads your Hotjar surveys through the Hotjar API and brings the surveys of the sites you choose, their questions, every response and every answer, with the respondent's device, browser, country, page and user attributes, plus the tags and sentiment of each answer.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in Hotjar. The Hotjar API does not export heatmaps or session recordings, so they are not available.

> [!WARNING]
>
> The Hotjar API gives access to survey responses only to organizations on an **Ask Scale** plan. Check your plan before setting up this source.

## Configuring Hotjar as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Hotjar option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The connector signs in with Hotjar **API credentials** (a Client ID and a Client Secret). Only a user with **Admin** permission in the Hotjar organization can create them:

1. In Hotjar, open **Settings** and click **API**.
2. Select the **organization** that owns the sites you want to sync.
3. Enter a name for the credentials (for example "Nekt").
4. Select the **scope** that gives access to survey responses.
5. Click **Generate credentials** and copy the Client ID and the Client Secret.

See [Hotjar's guide to setting up the API](https://help.hotjar.com/hc/en-us/articles/36819965653009-How-to-Set-Up-the-Hotjar-API).

> [!WARNING]
>
> Hotjar API credentials **expire one year after they are created** and cannot be extended. Generate new credentials before that date and update them in this source, or the syncs will stop.

The following configurations are available:

* **Client ID**: The Client ID of the Hotjar API credentials.
* **Client Secret**: The Client Secret of the same credentials.
* **Site IDs**: The IDs of the Hotjar sites whose surveys you want to sync. Each Site ID is the number shown next to the site on the **Sites & Organizations** page in Hotjar. Every site must belong to the organization the credentials were generated for.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: every Hotjar table is synced as **Full table**: on every sync we read the current state of your surveys and responses. The Hotjar API cannot filter responses by date, and a response keeps changing after it is submitted (a partial response is completed, tags and sentiment are edited), so each sync reads everything again.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

### What happens when access is missing

* If the credentials are wrong, deleted or expired, the sync fails and no table is changed.
* If one of the Site IDs cannot be read with the credentials (a site of another organization, or a wrong number), the sync fails and no table is changed, because every table holds the data of all the sites.
* If the credentials can read the surveys but not the survey responses (the plan is not Ask Scale, or the credentials lack the survey responses scope), the **Survey Responses** and **Survey Response Answers** tables are skipped and not updated, the other tables keep syncing, and the sync log says what to fix.
* If a table that had rows comes back completely empty, that table's sync fails instead of emptying it, and the log says so. If you really removed all that data in Hotjar, run a **Full sync** of the source to accept the empty table.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Sync | Description |
| - | - | - | - |
| Surveys | `surveys` | Full table | Every survey of the selected sites: name, type, status and dates. |
| Survey Questions | `survey_questions` | Full table | Every question of every survey, in order, with its type, options and scale labels. |
| Survey Responses | `survey_responses` | Full table | Every response to every survey, with the respondent's device, browser, country, page and user attributes. |
| Survey Response Answers | `survey_response_answers` | Full table | One row per answer of each response, with the question's text and type, the answer, the comment, the tags and the sentiment. |

> [!NOTE]
>
> Nested information (the options of a question, the user attributes and the answers of a response) comes as JSON text. To analyze answers, use **Survey Response Answers**, which already has one row per answer joined with its question.

## Fields by stream

> [accordion] Surveys
>
> Every survey of the configured sites. Read in full on every sync.
>
> Table: `surveys` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the survey in Hotjar. |
> | `site_id` | Integer | Identifier of the Hotjar site the survey belongs to. |
> | `name` | String | Name of the survey, as shown in Hotjar. |
> | `type` | String | Type of the survey: link, full\_screen or popover. |
> | `is_enabled` | Boolean | Whether the survey is enabled (collecting responses). |
> | `sentiment_analysis_enabled` | Boolean | Whether the survey's text answers go through Hotjar's sentiment analysis. |
> | `created_time` | Datetime | When the survey was created. |
> | `updated_time` | Datetime | When the survey was last updated, as sent by Hotjar. |
> | `question_count` | Integer | Number of questions in the survey, including statements and the thank-you step. |
> | `url` | String | Path of the survey in the Hotjar API. |
> | `responses_url` | String | Path of the survey's responses in the Hotjar API. |

> [accordion] Survey Questions
>
> Every question of every survey, in the survey's order. Read in full on every sync.
>
> Table: `survey_questions` · Primary key: `survey_id`, `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `survey_id` | String | Identifier of the survey the question belongs to. |
> | `id` | String | Unique identifier of the question (`question_id` in Survey Response Answers). |
> | `site_id` | Integer | Identifier of the Hotjar site the survey belongs to. |
> | `position` | Integer | Position of the question in the survey, starting at 1. |
> | `type` | String | Type of the question: reaction, long-text, short-text, single-option, multiple-option, email, rating-1-5, rating-1-7, nps, statement or thank-you. |
> | `text` | String | Text of the question, as shown to the respondent. |
> | `is_required` | Boolean | Whether the respondent must answer the question. |
> | `image_url` | String | URL of the image shown with the question, if any. |
> | `choices` | String | Options the respondent can pick, for single-option and multiple-option questions (JSON array of objects with `text` and `allow_comment`). |
> | `low_label` | String | Label of the lowest score, for rating, nps and reaction questions. |
> | `high_label` | String | Label of the highest score, for rating, nps and reaction questions. |

> [accordion] Survey Responses
>
> Every response to every survey. Read in full on every sync.
>
> Table: `survey_responses` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Unique identifier of the survey response. |
> | `survey_id` | String | Identifier of the survey answered. |
> | `site_id` | Integer | Identifier of the Hotjar site the survey belongs to. |
> | `created_time` | Datetime | When the response was submitted. |
> | `is_complete` | Boolean | Whether the respondent completed the survey (false for partial responses). |
> | `hotjar_user_id` | String | Hotjar's identifier of the visitor who answered. |
> | `device` | String | Device type used to answer: desktop, tablet or mobile. |
> | `browser` | String | Browser in which the response was captured. |
> | `os` | String | Operating system of the respondent. |
> | `country` | String | Two-letter (ISO 3166) code of the respondent's country. |
> | `response_origin_url` | String | URL of the page where the response was submitted. |
> | `recording_url` | String | Link to the Hotjar recording that contains the response, if one exists. |
> | `window_width` | Integer | Width of the respondent's browser window, in pixels. |
> | `window_height` | Integer | Height of the respondent's browser window, in pixels. |
> | `user_attributes` | String | User attributes sent to Hotjar through its Identify API for this visitor (JSON array of objects with `name` and `value`). |
> | `answers` | String | Answers of the response (JSON array). The same answers, one row each, are in Survey Response Answers. |

> [accordion] Survey Response Answers
>
> One row per answer of every response, with the question's text and type. Read in full on every sync.
>
> Table: `survey_response_answers` · Primary key: `response_id`, `answer_index` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `response_id` | String | Identifier of the response the answer belongs to (`id` in Survey Responses). |
> | `answer_index` | Integer | Position of the answer within its response, starting at 1. |
> | `survey_id` | String | Identifier of the survey answered. |
> | `site_id` | Integer | Identifier of the Hotjar site the survey belongs to. |
> | `question_id` | String | Identifier of the question answered (`id` in Survey Questions). |
> | `question_type` | String | Type of the question answered, from the survey's current questions (empty if the question no longer exists). |
> | `question_text` | String | Text of the question answered, from the survey's current questions (empty if the question no longer exists). |
> | `answer` | String | The answer, as sent by Hotjar: the text, the chosen option, or the score of rating and nps questions (for example "10"). |
> | `comment` | String | Comment the respondent added to the chosen option, if any. |
> | `tags` | Array of strings | Names of the tags given to the answer in Hotjar. |
> | `sentiment` | String | Sentiment of a text answer: positive, negative or neutral. Empty for non-text answers, or when sentiment analysis is not part of your plan. |
> | `response_created_time` | Datetime | When the response was submitted. |

## Implementation Notes

* **Survey responses need an Ask Scale plan.** On other plans Hotjar refuses survey responses through its API. Hotjar does not document whether the list of surveys (the Surveys and Survey Questions tables) is available on other plans; this will be confirmed on the first syncs. If Hotjar refuses only the responses, the two response tables are skipped and the survey tables keep syncing.
* **Credentials expire after one year.** Generate new ones in Hotjar (Settings > API) before they expire and update this source.
* **Everything is read again on every sync.** The Hotjar API returns responses newest first and cannot filter them by date, so each sync reads every response of every survey. Large accounts take longer to sync.
* **Scores come as text.** The `answer` field keeps the value as Hotjar sends it; cast it to a number in your queries for nps and rating questions (for example `CAST(answer AS INT)`).
* **Not available through the Hotjar API**: heatmaps, session recordings, feedback widgets, funnels and events. The Hotjar User Lookup feature (privacy requests) is not used by this connector.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.