HubSpot Visitor Identification

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

★ Only Publicly Available OpenAPI DocumentIdentity AuthAuthenticationapiKey, oauth21 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.

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

GET STARTED

Start building with Visitor Identification API

Explore with Jentic

View OpenAPI Document

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.

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?

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

Time to first call

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.