HubSpot Analytics - Custom Behavioral Events

Name: HubSpot Analytics - Custom Behavioral Events API
Brand: HubSpot Analytics - Custom Behavioral Events
Availability: InStock

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.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-analytics-api" | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-analytics-api" | 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 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

GET STARTED

Start building with HubSpot Analytics - Custom Behavioral Events API

Explore with Jentic One

View OpenAPI Document

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 your Jentic One instance 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.

Why Jentic?

What agents get from Jentic-routed access to this vendor.

Setup

Wiring HubSpot Analytics custom behavioral events by hand means choosing between its hapikey query, OAuth, and private-app auth, keeping the api.hubapi.com host straight, and handling errors yourself. Through Jentic you install once, import HubSpot Analytics from the API Directory, store the credential once, and your agent calls it.

Permission scoping

This API exposes one send operation, so scope your agent to the operation it needs: sending an instance of a pre-defined behavioral event. You choose the operations it may call, so nothing beyond that send is included in the allowed set.

Credential isolation

Your HubSpot credential is stored once, encrypted, by your own Jentic One instance and injected per call at execution time. It never enters the agent's prompt, logs, or context.

Intent-based discovery

Agents search Jentic by intent such as 'send a behavioral event to HubSpot', and Jentic returns the POST /events/v3/send operation with its input schema (eventName, email, properties) so the agent calls the right endpoint without browsing the reference docs.

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 with Jentic One, the self-hosted execution layer.

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.

Can I limit what my agent is allowed to do with the HubSpot Analytics Custom Behavioral Events API?

Yes. This API exposes a single write operation, POST /events/v3/send, and because you run Jentic One yourself, your own rules decide which operations the agent may call. You can grant only that send operation, so the agent can emit a pre-defined behavioral event against a contact but cannot reach anything outside that call. The HubSpot credential stays with your self-hosted instance and is injected at execution time, never handed to the agent.