--- title: "Batch insert events" method: POST path: "/integrators/timeline/2026-09/events/batch" tags: ["Batch"] --- # Batch insert events `POST /integrators/timeline/2026-09/events/batch` ## Request - Base URL: `https://api.hubapi.com` - URL: `https://api.hubapi.com/integrators/timeline/2026-09/events/batch` - Auth: one of: - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.highly_sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.contacts.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.schemas.contacts.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.companies.highly_sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.schemas.companies.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.schemas.deals.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.deals.highly_sensitive.write.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `tickets.sensitive.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `tickets.highly_sensitive.v2` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.tickets.highly_sensitive.write` - OAuth 2 - Authorization code: `https://app.hubspot.com/oauth/authorize` - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `crm.objects.tickets.sensitive.write` Insert a batch of new App Event occurrences into the timeline. Each occurrence in the batch is immutable, and if an occurrence with the same ID already exists, the entire batch will be rejected. The batch can include occurrences from multiple event types, but all must belong to a single portal. ## Request body - BatchInputAppEventOccurrence - `inputs` AppEventOccurrence[], required: An array of AppEventOccurrence objects, each representing an individual app event occurrence to be included in the batch. This property is required. - `domain` string: The domain associated with the event occurrence, represented as a string. - `email` string: The email address associated with the event occurrence, represented as a string. - `eventTypeName` string, required: The name of the event type, represented as a string. - `extraData` object: An object containing additional data related to the event occurrence. - `id` string, required: The unique identifier for this event occurrence, represented as a string. - `objectId` string: The unique identifier of the object related to the event, represented as a string. - `objectTypeFullyQualifiedName` string: The fully qualified name of the object type associated with the event, represented as a string. - `properties` object, required: A map of custom property names to their values, represented as an object with string values. - `timelineIFrame` TimelineEventIFrame - `headerLabel` string, required: The label of the modal window that displays the iframe contents. - `height` integer, required: The height of the modal window in pixels. - `linkLabel` string, required: The text displaying the link that will display the iframe. - `url` string, required: The URI of the iframe contents. - `width` integer, required: The width of the modal window in pixels. - `timestamp` string, date-time: The date and time when the event occurred, represented in ISO 8601 format. - `utk` string: The user token key (utk) associated with the event, represented as a string. ## Response `200` successful operation - BatchResponseAppEventOccurrence - `completedAt` string, date-time, required: The date and time when the batch operation was completed, in ISO 8601 format. - `errors` StandardError[]: An array of StandardError objects detailing any errors that occurred during the batch operation. - `category` string, required: The category of the error. - `context` object, required: The context of the error, potentially including occurrence information. - `errors` ErrorDetail[], required: An array of ErrorDetail objects providing further information about the error. - `code` string: The status code associated with the error detail - `context` object: Context about the error condition - `in` string: The name of the field or parameter in which the error was found. - `message` string, required: A human readable message describing the error along with remediation steps where appropriate - `subCategory` string: A specific category that contains more specific detail about the error - `id` string: The error ID, if any. - `links` object, required: Links to any helpful documentation. - `message` string, required: The error message, if any. - `status` string, required: The resulting status of the batch operation. - `subCategory` object: Sub category of the error, if any. - `links` object: A map of link names to associated URIs that provide additional information about the batch operation. - `numErrors` integer: The number of errors encountered during the batch operation. - `requestedAt` string, date-time: The date and time when the batch operation was requested, in ISO 8601 format. - `results` AppEventOccurrence[], required: An array of AppEventOccurrence objects representing the results of the batch operation. - `domain` string: The domain associated with the event occurrence, represented as a string. - `email` string: The email address associated with the event occurrence, represented as a string. - `eventTypeName` string, required: The name of the event type, represented as a string. - `extraData` object: An object containing additional data related to the event occurrence. - `id` string, required: The unique identifier for this event occurrence, represented as a string. - `objectId` string: The unique identifier of the object related to the event, represented as a string. - `objectTypeFullyQualifiedName` string: The fully qualified name of the object type associated with the event, represented as a string. - `properties` object, required: A map of custom property names to their values, represented as an object with string values. - `timelineIFrame` TimelineEventIFrame - `headerLabel` string, required: The label of the modal window that displays the iframe contents. - `height` integer, required: The height of the modal window in pixels. - `linkLabel` string, required: The text displaying the link that will display the iframe. - `url` string, required: The URI of the iframe contents. - `width` integer, required: The width of the modal window in pixels. - `timestamp` string, date-time: The date and time when the event occurred, represented in ISO 8601 format. - `utk` string: The user token key (utk) associated with the event, represented as a string. - `startedAt` string, date-time, required: The date and time when the batch operation started, in ISO 8601 format. - `status` 'CANCELED' | 'COMPLETE' | 'PENDING' | 'PROCESSING', required: The current status of the batch operation. Valid values include 'PENDING', 'PROCESSING', 'CANCELED', and 'COMPLETE'. ## Other responses - `400`: One or more occurrences has a validation error that prevented us from accepting them for persistence. The response body will contain details about the validation error. Occurrence batch insert request rejected, none were accepted. - `409`: One or more occurrence in the batch already exist. Occurrences are immutable. Occurrence insert request rejected, none were accepted. - `default`: An error occurred. ## Changes - **2026-10-10** (2026-09) `432dbe0bb045`: 2 info - the security scope `crm.objects.contacts.highly_sensitive.write.v2` was added to the endpoint's security scheme `oauth2` - the security scope `timeline-write` was removed from the endpoint's security scheme `oauth2` - **2026-09-09** (2026-09) `52b722be726a`: 2 info - the security scope `crm.objects.contacts.highly_sensitive.write.v2` was added to the endpoint's security scheme `oauth2` - the security scope `timeline-write` was removed from the endpoint's security scheme `oauth2` - **2026-09-08** (2026-09) `b8a492d17795`: 2 info - the security scope `crm.objects.contacts.highly_sensitive.write.v2` was added to the endpoint's security scheme `oauth2` - the security scope `timeline` was removed from the endpoint's security scheme `oauth2` [Operation history](https://skmtc.dev/hubspot/apis/crm-timeline/changes/integrators/timeline/2026-09/events/batch/post.md) --- [API](https://skmtc.dev/hubspot/apis/crm-timeline.md) - [All operations](https://skmtc.dev/hubspot/apis/crm-timeline/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/crm-timeline/revisions/432dbe0bb045?raw)