HubSpot Visitor Identification
Browse all Hubapi APIsAgent-ready OpenAPI document · curated by JenticIdentity AuthAuthenticationapiKey, oauth21 EndpointsREST
Know of an official OpenAPI document? Contribute it →
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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-visitor-identification" | 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-visitor-identification" | 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 your Jentic One instance.
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?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring HubSpot Visitor Identification by hand means handling both app-token and OAuth 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 an identification token that links an authenticated visitor to the chat widget, 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 visitor to the hubspot chat widget', 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 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 with Jentic One, the self-hosted execution layer.
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.
Can I limit what my agent is allowed to do with the HubSpot Visitor Identification API?
Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. This API exposes a single operation, POST /conversations/v3/visitor-identification/tokens/create, which mints an identification token from the visitor details in the request body, so you can scope the agent to just that one call and nothing else. Your HubSpot credential stays in your self-hosted instance and is injected only at execution time, never reaching the agent's prompt or logs.
GET STARTED