Visitor Identification
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
COMMUNITYBEARER0 INSTALLS
OpenAPI Specificationv3.0
{
"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"
]
}