HubSpot Visitor Identification

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

★ Only Publicly Available OpenAPI DocumentCommunicationsChat Messagingoauth2, apiKey1 Endpoints

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.

Step 1: 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

Step 2: 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

GET STARTED

Start building with Visitor Identification API

Explore with Jentic

View OpenAPI Document

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.

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?

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

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.

Time to first call

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.