openapi: 3.0.1
servers:
  - url: https://api.hubapi.com/
info:
  description: The Visitor Identification API allows you to pass identification information to the HubSpot chat widget for otherwise unknown visitors that were verified by your own authentication system.
  title: Visitor Identification
  version: v3
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_developers.hubspot.com_hubfs_assets_hubspot.com_buzz_HubSpotOpenGraph.png
  x-origin:
    - format: openapi
      url: https://api.hubspot.com/api-catalog-public/v1/apis/conversations/v3/visitor-identification
      version: "3.0"
  x-providerName: hubapi.com
  x-serviceName: conversations
tags:
  - description: Operations to generate a token
    name: Generate
paths:
  /conversations/v3/visitor-identification/tokens/create:
    post:
      description: Generates a new visitor identification token. This token will be unique every time this endpoint is called, even if called with the same email address. This token is temporary and will expire after 12 hours
      operationId: post-/visitor-identification/v3/tokens/create_generateToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IdentificationTokenGenerationRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IdentificationTokenResponse"
          description: successful operation
        default:
          $ref: "#/components/responses/Error"
      security:
        - hapikey: []
        - oauth2_legacy:
            - conversations.visitor_identification.tokens.create
        - private_apps_legacy: []
      summary: Generate a token
      tags:
        - Generate
components:
  responses:
    Error:
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/Error"
      description: An error occurred.
  schemas:
    Error:
      example:
        category: VALIDATION_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
        message: Invalid input (details will vary based on the error)
      properties:
        category:
          description: The error category
          type: string
        context:
          additionalProperties:
            items:
              type: string
            type: array
          description: Context about the error condition
          example:
            invalidPropertyName:
              - propertyValue
            missingScopes:
              - scope1
              - scope2
          type: object
        correlationId:
          description: A unique identifier for the request. Include this value with any error reports or support tickets
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
          format: uuid
          type: string
        errors:
          description: further information about the error
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type: array
        links:
          additionalProperties:
            type: string
          description: A map of link names to associated URIs containing documentation about the error or recommended remediation steps
          type: object
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          example: An error occurred
          type: string
        subCategory:
          description: A specific category that contains more specific detail about the error
          type: string
      required:
        - category
        - correlationId
        - message
      type: object
    ErrorDetail:
      properties:
        code:
          description: The status code associated with the error detail
          type: string
        context:
          additionalProperties:
            items:
              type: string
            type: array
          description: Context about the error condition
          example:
            missingScopes:
              - scope1
              - scope2
          type: object
        in:
          description: The name of the field or parameter in which the error was found.
          type: string
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          type: string
        subCategory:
          description: A specific category that contains more specific detail about the error
          type: string
      required:
        - message
      type: object
    IdentificationTokenGenerationRequest:
      description: Information used to generate a token
      example:
        email: visitor-email@example.com
        firstName: Gob
        lastName: Bluth
      properties:
        email:
          description: The email of the visitor that you wish to identify
          type: string
        firstName:
          description: The first name of the visitor that you wish to identify. This value will only be set in HubSpot for new contacts and existing contacts where first name is unknown. Optional.
          type: string
        lastName:
          description: The last name of the visitor that you wish to identify. This value will only be set in HubSpot for new contacts and existing contacts where last name is unknown. Optional.
          type: string
      required:
        - email
      type: object
    IdentificationTokenResponse:
      description: The identification token to be passed to the Conversations JS API to identify the visitor
      example:
        token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
      properties:
        token:
          type: string
      required:
        - token
      type: object
  securitySchemes:
    hapikey:
      in: query
      name: hapikey
      type: apiKey
    oauth2_legacy:
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          scopes:
            conversations.visitor_identification.tokens.create: Fetch identification tokens for authenticated website visitors interacting with the HubSpot chat widget
          tokenUrl: https://api.hubapi.com/oauth/v1/token
      type: oauth2
    private_apps_legacy:
      in: header
      name: private-app-legacy
      type: apiKey
x-hubspot-available-client-libraries:
  - PHP
  - Node
  - Python
  - Ruby
