canonical: https://jentic.com/apis/hubapi.com/hubspot-analytics-api

# HubSpot Analytics - 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.

## For AI 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.

## Scope

Does not define event schemas, query analytics reports, or read event history - use only for sending instances of pre-defined custom behavioral events.

## Capabilities

- 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

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

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: Search Jentic for send a hubspot behavioral event, load /events/v3/send, and execute with eventName, email, and the properties dict.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /events/v3/send | Send a custom behavioral event for a contact |

## Key resources

- **Behavioral Events Tracking** — Send a custom behavioral event for a HubSpot contact

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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.

## Related APIs

- **HubSpot Custom Behavioral Events API** — The same /events/v3/send endpoint surfaced under HubSpot's CRM developer docs
- **HubSpot Events API** — Read CRM event history rather than write custom behavioral events in
- **Mixpanel** — Dedicated product analytics platform with deeper funnel and cohort analysis

## FAQ

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