HubSpot Visitor Identification
Browse all Hubapi APIsAgent-ready OpenAPI document · curated by JenticCommunicationsChat Messagingoauth2, apiKey1 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Issue identification tokens that let your app authenticate signed-in visitors to the HubSpot chat widget so conversations attach to the correct HubSpot contact.
Use for: I need to generate an identification token for the HubSpot chat widget, Authenticate a signed-in user with HubSpot live chat, Pass a user's email to HubSpot chat without exposing it client-side, Find the visitor token endpoint for HubSpot conversations
Not supported: Does not handle inbox message retrieval, conversation routing, or chatbot configuration - use for issuing visitor identification tokens only.
Jentic publishes the only available OpenAPI specification for HubSpot Visitor Identification, keeping it validated and agent-ready. The Visitor Identification API issues identification tokens that pass authenticated visitor information to the HubSpot chat widget. When a visitor is signed in to your own application, you can vouch for their identity and the chat widget will associate the conversation with the matching HubSpot contact instead of treating them as anonymous. It is the bridge between your app's auth system and HubSpot's live chat surface.
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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-conversations-api" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-conversations-api" | 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.
Generate a visitor identification token for an authenticated user
Pass an email and metadata that links chat conversations to HubSpot contacts
Authenticate the visitor server-side so the chat widget never trusts the browser alone
Attach custom firstName and lastName values to a chat session
Suppress duplicate anonymous chat threads for known users
Bridge an external SSO session into HubSpot's chat widget
Use Cases
Patterns agents use Visitor Identification API for, with concrete tasks.
★ Authenticated Live Chat
When a customer is signed in to your app or portal, the backend mints a HubSpot visitor identification token tied to their email. The frontend passes that token to the HubSpot chat widget, which then shows the conversation under the matching HubSpot contact and stores all messages on the right record. Agents see the customer's history immediately rather than triaging an anonymous visitor.
Call POST /conversations/v3/visitor-identification/tokens/create with email 'jane@example.com', firstName 'Jane', lastName 'Doe' and return the token to the frontend
SSO-Backed Chat Bridge
Companies with SSO (Okta, Azure AD, Auth0) need a way to extend that trust into HubSpot's chat widget without exposing identity tokens to the browser. The Visitor Identification API accepts the verified email server-side and returns a short-lived token that the widget uses to assert identity to HubSpot. This avoids the spoofing risk of letting the browser claim an email directly.
After validating the SSO session, call the visitor identification endpoint with the verified email and inject the returned token into the HubSpot chat widget's identificationToken field
Duplicate Contact Prevention
Without identification, every browser session is a separate anonymous visitor. After a few visits the CRM accumulates duplicate contact records that have to be merged. By minting an identification token on every authenticated page load, the chat widget always associates with the same HubSpot contact, eliminating the duplicate-creation pattern and keeping conversation history in one place.
On every authenticated page load, refresh the visitor identification token by POSTing the user's email and update the chat widget identificationToken before chat opens
Agent-Driven Chat Identity Provisioning
An AI agent that runs the company's chat tooling uses Jentic to mint visitor tokens at session start. It searches for 'identify hubspot chat visitor', loads the schema, and executes the call with the authenticated user's email so the chat widget always recognises the contact.
Search Jentic for 'identify hubspot chat visitor', load the schema, and call POST /conversations/v3/visitor-identification/tokens/create for the current user's email
Key Endpoints
1 endpoints — jentic publishes the only available openapi specification for hubspot visitor identification, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/conversations/v3/visitor-identification/tokens/create
Create a visitor identification token for a known email address
POST
/conversations/v3/visitor-identification/tokens/create
Create a visitor identification token for a known email address
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring HubSpot Visitor Identification by hand means handling both OAuth and app-token auth against api.hubapi.com and keeping the token-minting call server-side yourself. Through Jentic you install once, import Visitor Identification from the API Directory, store the credential once, and your agent calls it.
Permission scoping
This API exposes one operation, minting a visitor identification token, and the visitor details travel in the request body. Limit the agent to that single operation, which is all this API offers.
Credential isolation
Your HubSpot credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'identify a logged-in hubspot chat visitor', and Jentic returns POST /conversations/v3/visitor-identification/tokens/create with its input schema so the agent mints valid tokens without browsing the reference docs.
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 HubSpot Visitor Identification?
HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call HubSpot Visitor Identification via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.
What authentication does the HubSpot Visitor Identification API use?
It accepts OAuth 2.0 access tokens, the private-app-legacy header for private apps, and the hapikey query parameter as a legacy fallback. Calls must be made server-side; the resulting visitor token is what the browser-side chat widget uses to assert identity.
Can the visitor token be reused across sessions?
No. The token returned by /conversations/v3/visitor-identification/tokens/create is short-lived and tied to a single browser session. Mint a new token whenever an authenticated page loads or when the chat widget initialises, rather than caching tokens across sessions.
What are the rate limits for the HubSpot Visitor Identification API?
Standard HubSpot API limits apply: 100 requests per 10 seconds per private app token and 110 per 10 seconds per OAuth app per portal. For sites with high concurrent authenticated traffic, mint tokens lazily on chat-widget open rather than on every page load.
How do I authenticate a signed-in user to HubSpot chat through Jentic?
Search Jentic for 'identify hubspot chat visitor', load the schema for POST /conversations/v3/visitor-identification/tokens/create, and execute server-side with the user's email and optional firstName/lastName. Pass the returned token to the chat widget's identificationToken field.
Is the HubSpot Conversations API free?
API access is included with any HubSpot subscription that has Service Hub or chat features. Visitor identification specifically requires a paid Service or Marketing Hub tier with chat enabled in the portal.
Can I limit what my agent is allowed to do with the HubSpot Conversations API?
Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use, and this API exposes only one operation: minting a visitor identification token via POST /conversations/v3/visitor-identification/tokens/create. You can scope the agent to that single token-creation call and no other, since it is all this API offers. Your HubSpot credential is stored by your own instance and injected only at execution time, so the agent never sees it directly.
GET STARTED