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-hubspot-api-use-case: You're building an integration to pass along website visitors to a chatflow you've configured in HubSpot, and ensure that visitors are associated with a known contact so support agents in your account know who they're helping.
  x-hubspot-documentation-banner: NONE
  x-hubspot-introduction: The visitor identification API allows you to identify users who navigate to your website that you've authenticated using your own authentication system.
  x-hubspot-product-tier-requirements:
    cms: PROFESSIONAL
    marketing: PROFESSIONAL
    sales: PROFESSIONAL
    service: PROFESSIONAL
  x-hubspot-related-documentation:
    - name: "Visitor Identification Guide "
      url: https://hubspot.dev/guides/api/conversation/visitor-identification
  x-logo:
    url: 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:
  - 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-/conversations/v3/visitor-identification/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:
        - 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
          example: VALIDATION_ERROR
          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
          example:
            knowledge-base: https://www.hubspot.com/products/service/knowledge-base
          type: object
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          example: Invalid input (details will vary based on the error)
          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
          example: visitor-email@example.com
          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.
          example: Gob
          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.
          example: Bluth
          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:
          description: ""
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
          type: string
      required:
        - token
      type: object
  securitySchemes:
    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
  - Ruby
  - Python
x-hubspot-documentation-banner: NONE
x-hubspot-product-tier-requirements:
  cms: PROFESSIONAL
  marketing: PROFESSIONAL
  sales: PROFESSIONAL
  service: PROFESSIONAL
