canonical: https://jentic.com/apis/hubapi.com/hubspot-visitor-identification

# HubSpot Visitor Identification

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.

## For AI 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.

## Scope

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.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: Search Jentic for 'generate a hubspot visitor identification token', load the schema, and execute with email and name from the authenticated session

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /conversations/v3/visitor-identification/tokens/create | Generate an identification token for an authenticated visitor |

## Key resources

- **Identification Tokens** — Generate a token that authenticates a known visitor to the HubSpot chat widget

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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

- **HubSpot Conversations API** — Read and manage the conversation threads created after a visitor is identified
- **HubSpot CRM API** — Read or update the CRM contact that the chat session is now attached to
- **Intercom API** — Intercom uses identity verification (HMAC user_hash) to bind chat to a known user
- **Drift API** — Drift offers a similar identity flow to attach chat sessions to known users

## FAQ

### 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.