Visitor Identification

Name: Visitor Identification API
Brand: Visitor Identification
Availability: InStock

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

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.

Install Jentic One Beta (Self-Hosted)

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 | sh

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 instance

Jentic 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

GET STARTED

Start building with Visitor Identification API

Explore with Jentic

View OpenAPI Document

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 document for Visitor Identification, keeping it validated and agent-ready.

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.

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

Complementary

HubSpot Conversations API

Read and manage the conversation threads created after a visitor is identified

Use after Visitor Identification to read messages and manage threads for the identified contact

Complementary

HubSpot CRM API

Read or update the CRM contact that the chat session is now attached to

Use to enrich the contact record once the chat is bound to a known visitor

Alternative

Intercom API

Intercom uses identity verification (HMAC user_hash) to bind chat to a known user

Choose Intercom when the live chat product is Intercom rather than HubSpot

Alternative

Drift API

Drift offers a similar identity flow to attach chat sessions to known users

Choose Drift when the conversation platform is Drift instead of HubSpot

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.