Hotjar REST API

openapi: 3.1.0
info:
  title: Hotjar REST API
  description: >-
    The Hotjar REST API provides programmatic access to Hotjar data and
    functionality. It allows developers to export survey responses, list
    surveys, automate user lookup and deletion requests, and integrate
    Hotjar data into external tools and workflows. The API uses OAuth
    client credentials authentication, returns JSON responses, supports
    cursor-based pagination, and is rate limited to 3000 requests per
    minute. It is available on Observe and Ask Scale plans.
  version: '1.0'
  contact:
    name: Hotjar Support
    url: https://help.hotjar.com
  termsOfService: https://www.hotjar.com/legal/policies/terms-of-service/
externalDocs:
  description: Hotjar API Reference
  url: https://help.hotjar.com/hc/en-us/articles/36820005914001-Hotjar-API-Reference
servers:
  - url: https://api.hotjar.io/v1
    description: Hotjar Production API Server
tags:
  - name: Authentication
    description: >-
      OAuth 2.0 client credentials authentication endpoints for obtaining
      access tokens.
  - name: Survey Responses
    description: >-
      Endpoints for exporting and listing survey response data with
      cursor-based pagination.
  - name: Surveys
    description: >-
      Endpoints for listing surveys and retrieving survey details for a
      specific site.
  - name: User Lookup
    description: >-
      Endpoints for looking up user data and submitting deletion requests
      for GDPR compliance.
security:
  - bearerAuth: []
paths:
  /oauth/token:
    post:
      operationId: createOAuthToken
      summary: Obtain an OAuth access token
      description: >-
        Obtains an OAuth 2.0 access token using the client credentials grant
        type. The request must be encoded as application/x-www-form-urlencoded
        and include the client_id, client_secret, and grant_type parameters.
        The returned access token should be included as a Bearer token in the
        Authorization header of subsequent API requests.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  description: >-
                    The OAuth 2.0 grant type. Must be set to client_credentials.
                client_id:
                  type: string
                  description: >-
                    The client ID from your Hotjar API key pair.
                client_secret:
                  type: string
                  description: >-
                    The client secret from your Hotjar API key pair.
      responses:
        '200':
          description: Successfully obtained access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthToken'
        '401':
          description: Invalid client credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /sites/{site_id}/surveys:
    get:
      operationId: listSurveys
      summary: List surveys for a site
      description: >-
        Returns a paginated list of surveys for a specific site. Supports
        cursor-based pagination and optionally includes question details
        in the response. The site_id can be found in the Sites and
        Organizations page in your Hotjar account.
      tags:
        - Surveys
      parameters:
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/WithQuestions'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successfully retrieved list of surveys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyListResponse'
        '401':
          description: Missing or invalid authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Site not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /sites/{site_id}/surveys/{survey_id}:
    get:
      operationId: getSurvey
      summary: Get a specific survey
      description: >-
        Returns the details of a specific survey for a site, including
        its questions, configuration, and status.
      tags:
        - Surveys
      parameters:
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/SurveyId'
      responses:
        '200':
          description: Successfully retrieved survey details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Survey'
        '401':
          description: Missing or invalid authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Survey or site not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /sites/{site_id}/surveys/{survey_id}/responses:
    get:
      operationId: listSurveyResponses
      summary: List survey responses
      description: >-
        Returns a paginated list of responses for a specific survey. Responses
        are sorted by creation date in descending order, with the most recent
        responses returned first. Supports cursor-based pagination with a
        maximum of 100 responses per page. Available on Ask Scale plans.
      tags:
        - Survey Responses
      parameters:
        - $ref: '#/components/parameters/SiteId'
        - $ref: '#/components/parameters/SurveyId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: Successfully retrieved list of survey responses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResponseListResponse'
        '401':
          description: Missing or invalid authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Survey or site not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /organizations/{organization_id}/user-lookup:
    post:
      operationId: userLookup
      summary: Look up or delete user data
      description: >-
        Looks up user data across sites in an organization and optionally
        deletes all associated data. This endpoint supports GDPR compliance
        by enabling automated user data lookup and deletion requests. At
        least one of data_subject_email or data_subject_site_id_to_user_id_map
        must be provided. Available on Observe and Ask Scale plans.
      tags:
        - User Lookup
      parameters:
        - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLookupRequest'
      responses:
        '200':
          description: Successfully processed user lookup or deletion request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserLookupResponse'
        '401':
          description: Missing or invalid authorization header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token obtained from the OAuth token endpoint using client
        credentials grant.

  parameters:
    SiteId:
      name: site_id
      in: path
      required: true
      description: >-
        The unique identifier for the site. Can be found in the Sites and
        Organizations page under the respective organization.
      schema:
        type: integer

    SurveyId:
      name: survey_id
      in: path
      required: true
      description: >-
        The unique identifier for the survey.
      schema:
        type: integer

    OrganizationId:
      name: organization_id
      in: path
      required: true
      description: >-
        The unique identifier for the organization.
      schema:
        type: integer

    WithQuestions:
      name: with_questions
      in: query
      required: false
      description: >-
        Flag indicating whether question information should be included
        in the response. Defaults to false.
      schema:
        type: boolean
        default: false

    Limit:
      name: limit
      in: query
      required: false
      description: >-
        The number of items to return per page. Maximum value is 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100

    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        The cursor value for fetching the next page of results. Obtained
        from the next_cursor field in a previous response.
      schema:
        type: string

  schemas:
    OAuthToken:
      type: object
      description: >-
        An OAuth 2.0 access token response returned after successful
        client credentials authentication.
      properties:
        access_token:
          type: string
          description: >-
            The access token to use in the Authorization header of API requests.
        token_type:
          type: string
          description: >-
            The type of token issued. Always bearer.
          enum:
            - bearer
        expires_in:
          type: integer
          description: >-
            The number of seconds until the access token expires.

    Survey:
      type: object
      description: >-
        A Hotjar survey with its configuration, status, and optional
        question details.
      properties:
        id:
          type: integer
          description: >-
            The unique identifier for the survey.
        name:
          type: string
          description: >-
            The name of the survey.
        type:
          type: string
          description: >-
            The type of survey, such as popover, fullscreen, or external link.
        is_enabled:
          type: boolean
          description: >-
            Whether the survey is currently active and collecting responses.
        created_time:
          type: string
          format: date-time
          description: >-
            The ISO 8601 timestamp when the survey was created.
        url:
          type: string
          description: >-
            The URL path to the survey resource in the API.
        responses_url:
          type: string
          description: >-
            The URL path to retrieve the survey responses.
        sentiment_analysis_enabled:
          type: boolean
          description: >-
            Whether sentiment analysis is enabled for this survey.
        questions:
          type: array
          description: >-
            The list of questions in the survey. Only included when
            with_questions parameter is set to true.
          items:
            $ref: '#/components/schemas/SurveyQuestion'

    SurveyQuestion:
      type: object
      description: >-
        A question within a Hotjar survey, including its type, text,
        and available answer options.
      properties:
        id:
          type: integer
          description: >-
            The unique identifier for the question.
        text:
          type: string
          description: >-
            The text content of the question displayed to respondents.
        type:
          type: string
          description: >-
            The type of question, such as long-text, short-text, rating,
            multiple-choice, or nps.
        is_required:
          type: boolean
          description: >-
            Whether the question requires an answer before submission.
        choices:
          type: array
          nullable: true
          description: >-
            The list of answer choices for multiple-choice questions.
            Null for open-ended question types.
          items:
            type: string
        labels:
          type: object
          nullable: true
          description: >-
            Labels for rating or scale questions. Null for other
            question types.
        image_url:
          type: string
          nullable: true
          description: >-
            URL of an image attached to the question. Null if no image
            is attached.

    SurveyResponse:
      type: object
      description: >-
        A single response to a Hotjar survey, containing the answers
        provided by a respondent.
      properties:
        id:
          type: string
          description: >-
            The unique identifier for the survey response.
        answers:
          type: array
          description: >-
            The list of answers provided in this response.
          items:
            $ref: '#/components/schemas/SurveyAnswer'
        comment:
          type: string
          nullable: true
          description: >-
            An optional comment provided by the respondent.
        tags:
          type: array
          description: >-
            Tags associated with this survey response.
          items:
            $ref: '#/components/schemas/SurveyResponseTag'

    SurveyAnswer:
      type: object
      description: >-
        An individual answer to a survey question within a response.
      properties:
        question_id:
          type: string
          description: >-
            The unique identifier of the question being answered.
        answer:
          type: string
          description: >-
            The text of the answer provided by the respondent.

    SurveyResponseTag:
      type: object
      description: >-
        A tag associated with a survey response for categorization
        and filtering.
      properties:
        name:
          type: string
          description: >-
            The name of the tag.

    SurveyListResponse:
      type: object
      description: >-
        A paginated list of surveys with cursor-based pagination support.
      properties:
        results:
          type: array
          description: >-
            The list of surveys returned in this page.
          items:
            $ref: '#/components/schemas/Survey'
        next_cursor:
          type: string
          nullable: true
          description: >-
            The cursor value to use for fetching the next page. Null when
            there are no more results.

    SurveyResponseListResponse:
      type: object
      description: >-
        A paginated list of survey responses with cursor-based pagination
        support.
      properties:
        results:
          type: array
          description: >-
            The list of survey responses returned in this page.
          items:
            $ref: '#/components/schemas/SurveyResponse'
        next_cursor:
          type: string
          nullable: true
          description: >-
            The cursor value to use for fetching the next page. Null when
            there are no more results.

    UserLookupRequest:
      type: object
      description: >-
        A request to look up or delete user data across sites in an
        organization. At least one of data_subject_email or
        data_subject_site_id_to_user_id_map must be provided.
      properties:
        data_subject_email:
          type: string
          format: email
          description: >-
            The email address of the data subject to look up.
        data_subject_site_id_to_user_id_map:
          type: object
          description: >-
            A map of site IDs to user IDs on your site, used when user
            attributes have been sent via the Identify API.
          additionalProperties:
            type: string
        delete_all_hits:
          type: boolean
          description: >-
            Whether to immediately delete all found data for the user.
            Set to true to submit a deletion request.
          default: false

    UserLookupResponse:
      type: object
      description: >-
        The result of a user lookup or deletion request.
      properties:
        status:
          type: string
          description: >-
            The status of the lookup or deletion request.
        message:
          type: string
          description: >-
            A human-readable message describing the result.

    Error:
      type: object
      description: >-
        An error response returned by the API when a request fails.
      properties:
        error:
          type: string
          description: >-
            The error type or code.
        message:
          type: string
          description: >-
            A human-readable description of the error.