HubSpot Visitor Identification
Browse all Hubapi APIs★ Only Publicly Available OpenAPI DocumentIdentity AuthAuthenticationapiKey, oauth21 EndpointsREST
For Agents
Generate identification tokens that link signed-in users from your auth system to the HubSpot chat widget so conversations attach to the correct CRM contact.
Use for: I need to identify a logged-in user to the HubSpot chat widget, Generate a visitor identification token for jane@example.com, Get the chat token so the widget can resume a known contact's thread, Set up server-side identification for the HubSpot live chat
Not supported: Does not send chat messages, manage conversations, or update CRM contact fields — use only for issuing identification tokens that link authenticated visitors to the HubSpot chat widget.
Jentic publishes the only available OpenAPI specification for Visitor Identification, keeping it validated and agent-ready. The HubSpot Visitor Identification API issues short-lived tokens that link a verified, signed-in user from your own authentication system to the HubSpot chat widget. By passing the generated token to the widget, the chat session is associated with a known contact instead of an anonymous visitor, so conversation history and CRM context follow the user. The API exposes one endpoint, POST /conversations/v3/visitor-identification/tokens/create, which is called server-side after your application has authenticated the user.
Install Jentic One Beta
Connect the Visitor Identification to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Visitor Identification, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Visitor Identification API.
Issue a short-lived identification token for an authenticated visitor's email
Bind a HubSpot chat widget session to a known CRM contact
Attach a first name and last name to the chat session at token creation
Continue an existing chat thread across page loads for an authenticated user
Replace anonymous chat threads with identified contact threads after sign-in
Use Cases
Patterns agents use Visitor Identification API for, with concrete tasks.
★ Identify signed-in users to live chat
When a user signs in to your web application, the backend should issue a HubSpot identification token so that any chat opened on the next page is linked to that user's CRM contact. POST /conversations/v3/visitor-identification/tokens/create accepts the verified email, optional first name, and last name, and returns a token your front-end passes to the HubSpot chat widget. This replaces anonymous chat threads with contact-attached ones from the first message.
Call POST /conversations/v3/visitor-identification/tokens/create with email=jane@example.com, firstName=Jane, lastName=Doe and pass the returned token to window.hsConversationsSettings.identificationToken
Resume the same chat thread across logins
Without identification, every browser session starts a new anonymous chat. By generating a token at the start of each authenticated session, the chat widget resumes the same conversation thread for the same contact across devices and visits. The backend calls the token endpoint once per session and the front-end loads the widget with the token attached.
On user login, call POST /conversations/v3/visitor-identification/tokens/create with the user's email and store the returned token in the session for the chat widget loader
Agent integration via Jentic
An onboarding agent that just verified a user's email can issue a HubSpot identification token in the same flow. Through Jentic the agent searches for the visitor identification operation, loads the schema, and executes with the verified email and name. The HubSpot private app token never leaves the Jentic vault.
Search Jentic for 'generate a hubspot visitor identification token', load the schema, and execute with email and name from the authenticated session
Key Endpoints
1 endpoints — jentic publishes the only available openapi specification for visitor identification, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/conversations/v3/visitor-identification/tokens/create
Generate an identification token for an authenticated visitor
POST
/conversations/v3/visitor-identification/tokens/create
Generate an identification token for an authenticated visitor
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot private app tokens or OAuth access tokens are stored encrypted in the Jentic vault. The token-creation call happens server-side through Jentic so the HubSpot credential never reaches the agent or the browser.
Intent-based discovery
Agents search Jentic with intents like 'identify a logged-in visitor to the HubSpot chat widget' and Jentic returns the matching POST /conversations/v3/visitor-identification/tokens/create operation with its input schema.
Time to first call
Direct integration: a few hours to wire credential management, the server endpoint, and front-end widget config. Through Jentic: under 30 minutes — search, load, execute against one endpoint.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Visitor Identification API through Jentic.
Why is there no official OpenAPI spec for Visitor Identification?
HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Visitor Identification via structured tooling. It is validated against the live API and kept up to date. Get started at https://app.jentic.com/sign-up.
What authentication does the HubSpot Visitor Identification API use?
The spec lists a private app token in the private-app-legacy header, OAuth 2.0, and a legacy hapikey query parameter. Production integrations should use a private app token or OAuth. The token endpoint must be called server-side because it requires a credential that should never reach the browser.
Can I attach a name to the chat session with the Visitor Identification API?
Yes. The request body to POST /conversations/v3/visitor-identification/tokens/create accepts firstName and lastName alongside email, so the chat thread shows the contact's name and HubSpot can match or create the CRM contact accordingly.
How long does an identification token last?
HubSpot identification tokens are short-lived session tokens designed to be issued once per authenticated session. The spec does not surface a numeric TTL — generate a fresh token on each user login or page reload that initialises the chat widget.
How do I generate an identification token through Jentic?
Search Jentic for 'generate a hubspot visitor identification token', load the schema for POST /conversations/v3/visitor-identification/tokens/create, and execute with the verified email and name. Jentic returns the token JSON which you forward to the chat widget loader.
Is the Visitor Identification API free?
The endpoint is included with HubSpot accounts that have access to live chat features. There is no per-call charge from HubSpot, but each call counts against the account's standard rate limit of around 100 requests per 10 seconds.
GET STARTED