HubSpot Analytics — Custom Behavioral Events
Browse all Hubapi APIs★ Only Publicly Available OpenAPI DocumentAnalyticsProduct AnalyticsapiKey, oauth21 EndpointsREST
For Agents
Send a custom behavioral event into HubSpot's analytics so the contact's record reflects the action and downstream lists or workflows can react.
Use for: I need to send a custom behavioral event into HubSpot Analytics, Track an activation event for a HubSpot contact, Fire a plan-upgrade event keyed by user email, Send a feature-engagement event for analytics segmentation
Not supported: Does not define event schemas, query analytics reports, or read event history — use only for sending instances of pre-defined custom behavioral events.
Jentic publishes the only available OpenAPI specification for HubSpot Analytics — Custom Behavioral Events, keeping it validated and agent-ready. This API is the analytics-side endpoint for landing custom behavioral events against HubSpot contacts so they show up in HubSpot's analytics, lists, and workflows alongside form submissions and page views. The single send endpoint accepts a defined event name, a contact identifier (email, utk, or objectId), and the event's typed property values.
Install Jentic One Beta
Connect the HubSpot Analytics — Custom Behavioral Events to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the HubSpot Analytics — Custom Behavioral Events, 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.
1
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 | sh2
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 instanceJentic 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 HubSpot Analytics — Custom Behavioral Events API.
Send a custom behavioral event for a contact via POST /events/v3/send
Identify the contact by email, utk, or HubSpot objectId on the same call
Pass typed event properties defined ahead of time in the HubSpot event schema
Drive analytics lists and workflow triggers from product-side activity
Land high-value lifecycle signals (trial, activation, upgrade) into the HubSpot contact timeline
Use Cases
Patterns agents use HubSpot Analytics — Custom Behavioral Events API for, with concrete tasks.
★ Land Product Signals in HubSpot Analytics
Send key product-side moments (activation, plan upgrade, churn risk) into HubSpot Analytics so they live on the contact timeline alongside marketing and web activity. POST to /events/v3/send with the event name, the contact identifier, and the event property values.
POST to /events/v3/send with eventName pe123_activated, email user@example.com, and properties {plan: pro}.
Trigger Lifecycle Workflows from Product Events
Marketing teams want HubSpot workflows to fire on real product behaviour, not synthetic page views. Sending a custom event named trial_completed or plan_upgraded fires any workflow listening for that event, eliminating polling-based integrations.
POST to /events/v3/send with eventName pe123_trial_completed and the user's email so the lifecycle workflow advances.
Cohort Segmentation by In-Product Behaviour
Segment HubSpot contacts by actions they took inside the product — for example, contacts who fired feature_used three times in the last week. Once events flow in via /events/v3/send, HubSpot active lists can filter on event recency and properties.
POST 200 feature_used events keyed by email to /events/v3/send, then build a HubSpot active list filtering on that event in the last 7 days.
AI Agent Behavioural Telemetry via Jentic
An AI agent that observes a meaningful user action — for example, completing onboarding — calls Jentic to record the event against the HubSpot contact, with credentials held in the Jentic vault and never exposed to the agent.
Search Jentic for send a hubspot behavioral event, load /events/v3/send, and execute with eventName, email, and the properties dict.
Key Endpoints
1 endpoints — jentic publishes the only available openapi specification for hubspot analytics — custom behavioral events, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/events/v3/send
Send a custom behavioral event for a contact
POST
/events/v3/send
Send a custom behavioral event for a contact
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot hapikeys, OAuth tokens, and private-app tokens are encrypted in the Jentic vault and injected per call. The agent never receives the raw secret.
Intent-based discovery
Agents search Jentic with intents like send a behavioral event to hubspot and Jentic returns /events/v3/send with the input schema (eventName, email, properties).
Time to first call
Direct integration: 1-2 hours for auth setup and event-schema wiring. Through Jentic: under 15 minutes once the event definitions exist in HubSpot.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using HubSpot Analytics — Custom Behavioral Events API through Jentic.
Why is there no official OpenAPI spec for HubSpot Analytics behavioral events?
HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call HubSpot Analytics — Custom Behavioral Events 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 this analytics events API use?
It supports HubSpot hapikey (query), OAuth 2.0 authorization code with the analytics.behavioral_events.send scope, and private-app legacy tokens (private-app-legacy header). Through Jentic, the credential is stored encrypted in the vault and injected at call time.
Can I send an event keyed by email?
Yes. The /events/v3/send body supports email, utk, or objectId as the contact identifier. Email is the simplest when the calling system already has the user's email.
What are the rate limits for sending behavioral events?
Standard HubSpot rate limits apply — typically 100 requests per 10 seconds per hapikey, higher under OAuth on Enterprise. Behavioral events can spike, so coordinate bulk sends with HubSpot support if you exceed normal volumes.
How do I send an analytics event through Jentic?
Search Jentic for send a hubspot behavioral event, load /events/v3/send, and execute with eventName (the internal event name like pe123_feature_used), the contact identifier (email or utk), and the properties payload defined in your HubSpot event schema.
How is this different from the Custom Behavioral Events API?
Both expose the same /events/v3/send operation. This entry is the analytics-API surfacing of the same endpoint, kept distinct in the catalogue because HubSpot's documentation groups it under Analytics. Calling either uses the same payload shape.
GET STARTED