Hotjar API

Hotjar is a comprehensive user behavior analytics platform that provides heatmaps, session recordings, surveys, and feedback tools to help businesses understand how users interact with their websites and applications, enabling data-driven improvements to user experience and conversion optimization.

Power end-to-end data operations for your Hotjar API API with Nexla. Our bi-directional Hotjar API connector is purpose-built for Hotjar API, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Hotjar API or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Hotjar API workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

Before creating a Hotjar API credential, you need to obtain a Client ID and Client Secret from your Hotjar account. The Client ID and Client Secret are required for token-based authentication with the Hotjar API.

To obtain your Client ID and Client Secret, you need to have a Hotjar account. Once you have access to your account, you can view and manage your API keys in your Hotjar account settings. The Client ID and Client Secret are used to obtain an access token using the OAuth2 client credentials flow. The access token is then sent in the Authorization header with the Bearer prefix for all API requests to the Hotjar API. For detailed information about API key setup and authentication, refer to the Hotjar API Reference documentation.

Authenticate

Credentials required

Field	Required	Secret	Description
Username Or Client ID	Yes	No	client_id must be set to your API key's client ID.
Password or Client Secret	Yes	Yes	client_secret must be set to your API key's client secret.

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

New Credential Overlay – Hotjar API

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

3. Enter your Hotjar Client ID in the Username Or Client ID field. This is the Client ID you obtained from your Hotjar API key settings. The Client ID is used along with the Client Secret to obtain an access token for API authentication.

   Your Hotjar Client ID can be found in your Hotjar account settings where you manage API keys. The Client ID is used along with the Client Secret to obtain an access token using the OAuth2 client credentials flow. For detailed information about finding your Client ID, see the Hotjar API Reference documentation.

4. Enter your Hotjar Client Secret in the Password or Client Secret field. This is the Client Secret you obtained from your Hotjar API key settings. The Client Secret is used along with the Client ID to obtain an access token for API authentication.

   Keep your Client Secret secure and do not share it publicly. The Client Secret provides access to your Hotjar account data and should be treated as sensitive information. Nexla automatically obtains and refreshes the access token as needed. For detailed information about finding your Client Secret, see the Hotjar API Reference documentation.

5. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Hotjar API connector tile, then select the credential that will be used to connect to the Hotjar account, and click Next; or, create a new Hotjar API credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Hotjar API endpoints. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

List Surveys

List Surveys

• Enter the site's unique identifier in the Site ID field. This ID can be found in the Sites & Organizations page under the respective organization in your Hotjar account.
• Optionally, enter the number of surveys to be returned in the Limit field. The maximum is 100. If not specified, the default limit will be used.
• Optionally, enter the cursor to be used for fetching a specific page in the Cursor field. The cursor is used for pagination to retrieve specific pages of results.
• Optionally, enter a flag (true/false) indicating whether the question information should be included in the response in the With Questions field. By default, question information is not included.
• The endpoint uses GET requests to https://help.hotjar.com/v1/sites/{site_id}/surveys where {site_id} is the Site ID you provide. The endpoint URL is automatically constructed based on the Hotjar API base URL and the site ID.
• The endpoint uses token-based pagination (iteration.type: paging.next.token) through the cursor mechanism. The response data path is $.results[*], which extracts all items from the results array in the API response. Additional metadata is also included from the root-level object.
• When a response includes a next_cursor value, Nexla automatically uses it as the cursor parameter for the subsequent request to fetch the next page of results until all surveys have been retrieved (when next_cursor is null).

This endpoint retrieves all surveys for a specific site in your Hotjar account. The endpoint supports pagination through the cursor mechanism, which allows you to retrieve large lists of surveys efficiently. You can optionally include question information in the response by setting the with_questions parameter to true. The response includes pagination metadata that indicates the current cursor and next cursor available. When next_cursor is null, all surveys have been retrieved. For detailed information about the API response format and available fields, see the Hotjar API Reference documentation.

List Survey Responses

List Survey Responses

• Enter the site's unique identifier in the Site ID field. This ID can be found in the Sites & Organizations page under the respective organization in your Hotjar account.
• Enter the survey's unique identifier in the Survey ID field. This is the unique identifier for the survey whose responses you want to retrieve.
• Optionally, enter the number of survey responses to be returned in the Limit field. The maximum is 100. If not specified, the default limit will be used.
• Optionally, enter the cursor to be used for fetching a specific page in the Cursor field. The cursor is used for pagination to retrieve specific pages of results.
• The endpoint uses GET requests to https://api.hotjar.io/v1/sites/{site_id}/surveys/{survey_id}/responses where {site_id} is the Site ID you provide and {survey_id} is the Survey ID you provide. The endpoint URL is automatically constructed based on the Hotjar API base URL, the site ID, and the survey ID.
• The endpoint uses token-based pagination (iteration.type: paging.next.token) through the cursor mechanism. The response data path is $.results[*], which extracts all items from the results array in the API response. Additional metadata is also included from the root-level object.
• When a response includes a next_cursor value, Nexla automatically uses it as the cursor parameter for the subsequent request to fetch the next page of results until all survey responses have been retrieved (when next_cursor is null).

This endpoint retrieves all responses for a specific survey in your Hotjar account. The endpoint supports pagination through the cursor mechanism, which allows you to retrieve large lists of survey responses efficiently. The response includes pagination metadata that indicates the current cursor and next cursor available. When next_cursor is null, all survey responses have been retrieved. For detailed information about the API response format and available fields, see the Hotjar API Reference documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

Hotjar API data sources can also be manually configured to ingest data from any valid Hotjar API endpoint, including endpoints not covered by the pre-built templates. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers. Hotjar API endpoints typically follow the pattern https://api.hotjar.io/v1/{endpoint_path} or https://help.hotjar.com/v1/{endpoint_path}, and return data in JSON format.

The endpoint requires token-based authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. The access token is obtained using the OAuth2 client credentials flow with your Client ID and Client Secret.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Hotjar API data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination

Click the + icon on the Nexset that will be sent to the Hotjar API destination, and select the Send to Destination option from the menu. Select the Hotjar API connector from the list of available destination connectors, then select the credential that will be used to connect to the Hotjar API organization, and click Next; or, create a new Hotjar API credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Hotjar API endpoints. Select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

User Lookup

Perform a user lookup (with optional deletion)

• Enter the organization's unique identifier in the Organization ID field. This ID can be found in the Sites & Organizations page next to the respective organization in your Hotjar account.
• The endpoint uses POST requests to https://api.hotjar.io/v1/organizations/{organization_id}/user-lookup where {organization_id} is the Organization ID you provide. The endpoint URL is automatically constructed based on the Hotjar API base URL and the organization ID.
• The endpoint sends data from your Nexset as the request body in JSON format. The request body is automatically formatted according to the schema fields and data mapping you configure. Each record in your Nexset will be sent as a JSON object containing the user lookup data.
• Batch mode is disabled by default for this endpoint. Each record in your Nexset will be sent as a separate API request to perform a user lookup. If you need to perform multiple user lookups, you can send multiple records, but each will be processed as a separate request.
• This endpoint does not automatically create a data source to track the responses received from the Hotjar API after each call.

The request body must be properly formatted JSON that matches the Hotjar API specification for user lookups. The endpoint requires token-based authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. The access token is obtained using the OAuth2 client credentials flow with your Client ID and Client Secret. The Content-Type: application/json header is automatically included in requests. This endpoint can perform user lookups with optional deletion functionality. Batch mode is disabled by default (batch.mode: false), so each record will be sent as a separate request. For detailed information about user lookups, including required fields, field names, and request formats, see the Hotjar API Reference documentation.

Manual configuration

Hotjar API destinations can also be manually configured to send data to any valid Hotjar API endpoint, including endpoints not covered by the pre-built templates. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks. Hotjar API endpoints typically follow the pattern https://api.hotjar.io/v1/{endpoint_path} and use JSON for request bodies.

The endpoint requires token-based authentication via the Authorization: Bearer {token} header, which is handled automatically by your credential configuration. The access token is obtained using the OAuth2 client credentials flow with your Client ID and Client Secret.

Save & activate

Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To send the data to the configured Hotjar API endpoint, open the destination resource menu, and select Activate.

The Nexset data will not be sent to the Hotjar API endpoint until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.