Visitor Identification

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

★ Only Publicly Available OpenAPI DocumentCommunicationsChat Messagingoauth2, apiKey1 EndpointsREST

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.

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.

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

GET STARTED

Start building with Visitor Identification API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for Visitor Identification, keeping it validated and agent-ready.

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.

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 though Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

HubSpot OAuth tokens, private app tokens, and legacy hapikeys are stored encrypted in the Jentic vault. Agents call the token endpoint server-side via Jentic so HubSpot credentials never enter the browser or the agent's prompt.

Intent-based discovery

Agents search by intent (e.g., 'identify hubspot chat visitor') and Jentic returns POST /conversations/v3/visitor-identification/tokens/create with its input schema, so the agent mints valid tokens without reading HubSpot's chat docs.

Time to first call

Direct HubSpot integration: 1-2 days for OAuth setup, server-side token minting, and chat widget wiring. Through Jentic: under 1 hour — search, load schema, execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Complementary

HubSpot CRM Cards

CRM cards display alongside the chat thread that visitor identification associates

Use Visitor Identification to attach a chat session to a contact; use CRM Cards to surface that contact's data inside HubSpot's record UI.

Complementary

HubSpot Webhooks API

Webhooks notify your backend when chat conversations or contacts change

Pair Visitor Identification (mint token) with the Webhooks API (receive contact-updated events) for a closed-loop chat integration.

Alternative

Intercom API

Intercom is a competing live chat platform with its own JWT-based visitor identification

Choose Intercom when the customer's chat platform is Intercom; choose HubSpot Visitor Identification when conversations need to live in the HubSpot CRM.

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 at https://app.jentic.com/sign-up.

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.