canonical: https://jentic.com/apis/hubspot.com/hubspot-events-send-event-completions

# HubSpot Events Send Event Completions

The HubSpot Send Event Completions API records occurrences of custom behavioural events against contacts in a HubSpot account. A single send endpoint posts one event with its eventName, contact identifiers (utk, email, or objectId), occurrence time, and property values, while a batch endpoint sends up to 100 occurrences in one call. Once recorded, occurrences flow into the same event store that powers HubSpot reporting, contact timelines, and workflow triggers - closing the loop between product behaviour and CRM segmentation.

## For AI agents

Send custom behavioural event occurrences (one or in batches up to 100) against HubSpot contacts so they appear in CRM timelines and trigger workflows.

## Scope

Does not query event history, define event schemas, or manage contacts - use for sending custom event occurrences only.

## Capabilities

- Send a single custom event occurrence against a contact identified by utk, email, or objectId
- Send up to 100 event occurrences in one batch call to reduce request overhead
- Attach typed property values to each occurrence to enrich downstream reporting
- Backdate event occurrences using the occurredAt timestamp for historical imports
- Trigger HubSpot workflows by emitting the event names that workflow enrolment criteria watch

## Use cases

### Real-Time Product Event Reporting

Forward product behaviour from your application to HubSpot in real time so the same events that exist in your product analytics also appear on the contact's CRM timeline. POST /events/v3/send delivers a single occurrence with its property bag and contact identifier; HubSpot then surfaces it in the contact record and exposes it to reporting and segmentation. Useful for closing the gap between product engagement and lifecycle marketing.

Example prompt: Call POST /events/v3/send with eventName=pe12345_checkout_completed, email=user@example.com, and properties {order_value: 49.99, currency: "USD"}.

### Batch Backfill of Historical Events

When migrating from another analytics tool or replaying logs, send historical occurrences in batches of up to 100 with explicit occurredAt timestamps so the events land on the correct day in HubSpot. The batch endpoint returns per-event status so failed items can be retried without resending the whole batch. Useful for one-off migrations and nightly reconciliation jobs.

Example prompt: Call POST /events/v3/send/batch with an inputs array of up to 100 event objects, each with eventName, email, occurredAt, and properties, then read the results array for per-item status.

### Workflow Triggering from External Systems

HubSpot workflows can enrol contacts based on a custom event firing. Send the enrolment event from an external system using POST /events/v3/send to trigger a nurture sequence, internal notification, or lifecycle stage update without writing the workflow logic in your own service. Useful for connecting webhooks and serverless functions to HubSpot automation.

Example prompt: Call POST /events/v3/send with the eventName that the target workflow listens for and the matching contact email.

### AI Agent Event Emission via Jentic

An AI agent reacting to a Stripe webhook (for example a successful payment) emits a corresponding HubSpot event so the marketing team's nurture flows can react. The agent searches Jentic for HubSpot event-send operations, loads the schema, and executes the call with the contact email, event name, and property bag pulled from the webhook payload. Jentic isolates the OAuth credential so the agent never handles tokens directly.

Example prompt: Search Jentic for "send hubspot custom event", load the schema for POST /events/v3/send, and execute with eventName, email, and properties from the inbound webhook.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /events/v3/send | Send a single custom event occurrence |
| POST | /events/v3/send/batch | Send up to 100 event occurrences in one batch |

## Key resources

- **Send** — Single-occurrence event submission against a contact.
- **Batch Send** — Up to 100 event occurrences submitted in one call with per-item status.

## Why Jentic

- **Setup:** Wiring HubSpot Event Completions by hand means learning its OAuth2 access token auth, targeting the api.hubapi.com host, and shaping single and batch event payloads yourself. Through Jentic you install once, import HubSpot Event Completions from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Event Completions API carries the event name and properties in the request body, so limit the agent to the operations it needs, such as sending a single custom event. You choose which operations are allowed, so the batch send is not included unless you add it.
- **Credential handling:** Your HubSpot access token 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.
- **Discovery method:** Agents search Jentic by intent such as 'send a HubSpot custom event', and Jentic returns the matching operation with its input schema so the agent posts to the right endpoint with the correct payload shape without browsing the reference docs.

## Related APIs

- **Events Manage Event Definitions** — Define the event schemas before sending occurrences
- **Events Events** — Read back the events you sent for verification
- **CRM Contacts** — Resolve or create the contacts referenced by event occurrences
- **Mixpanel** — Higher-throughput event ingestion focused on product analytics

## FAQ

### What authentication does the Send Event Completions API use?

It accepts HubSpot OAuth 2.0 access tokens or private app tokens, sent as Bearer in the Authorization header. Through Jentic, the token is stored encrypted in your Jentic One instance and never enters the agent's context.

### Can I send events in batches?

Yes. POST /events/v3/send/batch accepts up to 100 event objects per call and returns a results array with per-event status so failed items can be retried individually.

### How do I identify the contact an event belongs to?

Each event payload accepts one of three identifiers: email, utk (HubSpot user token cookie), or objectId (the CRM contact id). Provide whichever you have; HubSpot will resolve the contact record from it.

### What are the rate limits for sending events?

Account-level limits are 100 requests per 10 seconds across HubSpot's authenticated APIs, with daily caps that depend on the subscription tier. Use the batch endpoint to fit more occurrences inside the per-second window.

### How do I send a HubSpot event through Jentic?

Run pip install jentic, search for "send hubspot custom event", load the schema for POST /events/v3/send, and execute with eventName, email, occurredAt, and properties. Run Jentic One, the self-hosted execution layer, to get an ak_* key.

### Does the eventName have to match an existing event definition?

Yes. The eventName must correspond to a custom event definition created via the Manage Event Definitions API, otherwise HubSpot rejects the occurrence. Internal event names typically take the form pe{portalId}_{eventName}.

### Can I limit what my agent is allowed to do with the HubSpot Send Event Completions API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent can use, so you can allow only the single-occurrence POST /events/v3/send call and withhold the batch POST /events/v3/send/batch endpoint unless you explicitly add it. Since the event name and property values travel in the request body, scoping the agent to just the send operation it needs keeps it from emitting occurrences or running batches you did not intend. The encrypted HubSpot token is injected at execution time and never enters the agent's context.