canonical: https://jentic.com/apis/hubapi.com/marketing-events-extension

# HubSpot Marketing Events Extension

Jentic publishes the only available OpenAPI specification for the Marketing Events Extension, keeping it validated and agent-ready. The Marketing Events Extension API registers external marketing events such as webinars, conferences, and virtual sessions inside HubSpot. Apps create or upsert events keyed by externalEventId, search and cancel events, and record per-attendee state transitions like REGISTERED, ATTENDED, or CANCELLED. The same surface configures app-level integration settings and delivers attendance updates by either contactId or email.

## For AI agents

Register external marketing events and per-attendee attendance state in HubSpot, keyed by externalEventId so a third-party event platform stays in sync with HubSpot CRM.

## Scope

Does not handle email sends, marketing campaign creation, or contact list management - use for marketing event registration and attendance state only.

## Capabilities

- Register a marketing event by externalEventId so HubSpot tracks attendance against contact records
- Upsert a batch of events to keep HubSpot in sync with an external event platform
- Record per-attendee state transitions (REGISTERED, ATTENDED, CANCELLED, NO_SHOW)
- Cancel or complete an event and propagate the change to attendee records
- Search marketing events by name, organiser, or time window
- Configure app-level integration settings for the marketing events extension
- Update attendee state by email when the contact is not yet known to HubSpot

## Use cases

### Webinar Platform Sync

Companies running webinars on Zoom, On24, or GoToWebinar push every event and attendance update into HubSpot via this API. The events upsert endpoint keeps HubSpot in sync with the event platform, and the per-state attendance endpoints record who registered and who actually attended. Marketing then segments and follows up based on attendance state.

Example prompt: Upsert event with externalEventId 'zoom-12345', name 'Q3 Product Launch Webinar', then call POST /marketing/v3/marketing-events/attendance/zoom-12345/ATTENDED/create with the contactIds who joined

### Email-Keyed Attendance

When attendees register on a third-party platform with an email that may not yet exist in HubSpot, the email-create and email-upsert variants of the attendance endpoint accept email addresses directly. HubSpot creates or updates the contact record to match and records the attendance state in the same call, so the integration does not have to look up contacts first.

Example prompt: Call POST /marketing/v3/marketing-events/attendance/zoom-12345/REGISTERED/email-create with email 'jane@example.com' and joinedAt timestamp

### Event Lifecycle Management

Events get postponed, cancelled, or completed and HubSpot's view needs to track each state. The cancel and complete endpoints transition the event itself, and the search endpoint helps the integration find existing events by name when an externalEventId is not known. The delete endpoint archives events that should no longer appear in marketing reports.

Example prompt: Search for events by name 'Product Launch Webinar', then call POST /marketing/v3/marketing-events/events/{externalEventId}/cancel for the matching event

### Agent-Driven Event Registration

An AI agent that runs the company's webinar operations uses Jentic to register attendees as they sign up on a third-party platform. It searches for 'register hubspot marketing event attendee', loads the schema, and posts the attendee state transition immediately so HubSpot's segmentation always reflects the current attendee list.

Example prompt: Search Jentic for 'mark hubspot event attendee', load the schema, and post the REGISTERED state transition for each new sign-up

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /marketing/v3/marketing-events/events/upsert | Upsert a batch of marketing events |
| POST | /marketing/v3/marketing-events/events/search | Search marketing events |
| POST | /marketing/v3/marketing-events/events/{externalEventId}/cancel | Cancel an event |
| POST | /marketing/v3/marketing-events/events/{externalEventId}/complete | Mark an event complete |
| POST | /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create | Record attendee state transition by contactId |
| POST | /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create | Record attendee state transition by email |
| GET | /marketing/v3/marketing-events/{appId}/settings | Get app-level marketing events settings |

## Key resources

- **Events** — Create, upsert, search, cancel, complete, and delete marketing events by externalEventId
- **Attendance** — Record per-attendee state transitions by contactId or email
- **Settings** — Configure app-level integration settings for the marketing events extension

## Why Jentic

- **Setup:** Wiring the HubSpot Marketing Events Extension by hand means handling both OAuth and app-token auth against api.hubapi.com and tracking external event ids and subscriber states across the upsert and attendance calls yourself. Through Jentic you install once, import the Marketing Events Extension from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** The event and attendance operations carry the external event id and subscriber state in the URL path while the payloads travel in the request body, so limit the agent to the operations it needs, such as upserting or searching events. You choose that set, so cancelling an event with the /cancel operation is not included unless you add it.
- **Credential handling:** 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.
- **Discovery method:** Agents search Jentic by intent such as 'create a hubspot marketing event', and Jentic returns POST /marketing/v3/marketing-events/events/upsert with its input schema, including the externalEventId, name, and time fields, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot Marketing Events Extension** — An equivalent listing of the same Marketing Events Extension API surface
- **HubSpot Events API** — The Events API reads CRM event timelines that marketing event attendance writes to
- **HubSpot Subscriptions** — Subscriptions store the consent that gates marketing follow-up after an event

## FAQ

### Why is there no official OpenAPI spec for the Marketing Events Extension?

HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Marketing Events Extension 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 Marketing Events Extension API use?

It accepts the developer hapikey query parameter, OAuth 2.0 access tokens, the private-app-legacy header, and the hapikey query parameter as a legacy fallback. Jentic stores all of these credential types in its encrypted vault and provides agents with scoped tokens at execution time.

### Can I record attendance for a contact that does not yet exist in HubSpot?

Yes. POST /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create accepts an email address directly. HubSpot creates or updates the contact record to match and records the attendance state in the same call, so no separate contact lookup is required.

### What are the rate limits for the Marketing Events Extension API?

Standard HubSpot API limits apply: 100 requests per 10 seconds per private app token and 110 per 10 seconds per OAuth app per portal. For high-volume webinar imports, use the events upsert batch endpoint and the email-upsert attendance variant rather than one call per attendee.

### How do I register a marketing event through Jentic?

Search Jentic for 'create hubspot marketing event', load the schema for POST /marketing/v3/marketing-events/events/upsert, and execute with an array of events keyed by externalEventId. For one event at a time, POST to /marketing/v3/marketing-events/events with the event payload.

### Is the Marketing Events Extension API free?

API access is included with any HubSpot subscription that has Marketing Hub features. Marketing event records appear on contact timelines and in Marketing Hub reports; reporting depth scales with the Marketing Hub subscription tier.

### Can I limit what my agent is allowed to do with the Marketing Events Extension API?

Yes. Because you run Jentic One yourself, your own rules decide which of the Marketing Events Extension operations the agent may call, so you can allow only what it needs, such as upserting and searching events, and recording attendance state by contactId or email. State-changing operations like cancelling or completing an event stay off limits unless you explicitly add them to the agent's set. Your HubSpot credential is stored once by your own instance and injected at execution time, never entering the agent's prompt or logs.