Send event occurrences - HubSpot docs

This feature is intended only for technology partners, and requires approval from HubSpot to use. To apply for app events access, or if you want to learn more about the functionality, please submit this in-app form.

After defining an event type schema and retrieving its fullyQualifiedName, you can send event occurrence data via the app events API. When sending event data, you’ll need to adhere to the schema you created earlier. Requests that don’t match the schema will fail validation and will not be captured by the app.

Please note: event occurrences are immutable. Once created, they cannot be updated or removed.

Sending event occurrences

Send a single occurrence
Send a batch of occurrences

To send a single event occurrence, make a POST request to /integrators/timeline/v4/events.In the request body, include the following:

The event data following the event type’s defined schema, along with the id of the CRM record to associate with the event occurrence.
The fullyQualifiedName value in a eventTypeName field. This value can either be your app’s uid defined in the top-level *-hsmeta.json file, or fullyQualifiedName returned from the /integrators/timeline/v4/types/projects API.

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
}

To send a batch of event occurrences, make a POST request to /integrators/timeline/v4/events/batch.In the request body, include up to 500 comma-separated event occurrence objects within an inputs array:

Each event occurrence object should adhere to your event type’s defined schema, and should also include the id of the CRM record to associate with the event occurrence.
Each occurrence object should also include the fullyQualifiedName value in a eventTypeName field. This value can either be your app’s uid defined in the top-level *-hsmeta.json file, or fullyQualifiedName returned from the /integrators/timeline/v4/types/projects API.
If any occurrences in the batch fail to validate, no occurrences from the batch will be accepted.

{
  "inputs": [
    {
      "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_100",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "mobileApp"
      },
      "extraData": {
        "surveyData": [
          {
            "question": "How was your login experience?",
            "answer": "Fine!"
          },
          {
            "question": "How likely are you to recommend logging in to a co-worker?",
            "answer": "Extremely likely"
          }
        ]
      }
    },
    {
      "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "id": "login_event_101",
      "objectId": "769851",
      "properties": {
        "customerName": "Tim",
        "loginLocation": "website"
      },
      "extraData": {}
    }
  ]
}

Fields marked with * are required.

Field	Type	Description
`eventTypeName`*	String	The fully qualified name of the event type, which you’ll use to identify the event via the API. This value can either be your app’s `uid` defined in the top-level `*-hsmeta.json` file, or can be obtained via the API after creating the event type. This value cannot be changed after creation.
`objectId`*	String	The ID of the CRM record to associate with the event occurrence. This field can be used for all types of CRM records, and is the recommended identifier. Learn more about CRM record association.
`objectTypeFullyQualifiedName`	Type	This field is required when the event type is configured for custom objects. Specifies the target custom object by its fullyQualifiedName, using the format `p{accountId}_{objectName}` (e.g., `p1234567_Cats`). Including this field when targeting a non-custom object event type will result in a rejected data send.
`email`	String	For contact association, you can provide the email address of the contact to associate. Learn more about CRM record association.
`utk`	String	For contact association, you can provide the usertoken of an existing contact to associate. Learn more about CRM record association.
`domain`	String	Include this field in addition to `objectId` to set the company’s `domain` property value. Learn more about CRM record association.
`timestamp`	String	Sets the time of the event occurrence (ISO 8601 format). If not provided, HubSpot will default to the timestamp of when the event occurrence data is sent.
`properties`	Object	Key-value pairs of property names and values for properties you’ve configured for the event type. An occurrence will be rejected if it contains properties not defined in the event type schema, or if the property type in the occurrence doesn’t match the property type defined in the event type schema. Learn more about event properties.
`extraData`	Object	Additional information which will be available to timeline rendering templates. Must be in valid JSON format.
`timelineIFrame`	Object	When included, the timeline card will include a hyperlink that allows users to open the linked contents in an iframe. Learn more about using iframes.
`id`	String	A unique identifier for the event occurrence. Must be unique within the event type across all accounts. If not provided, HubSpot will generate a random UUID. When multiple events have the same ID within a year, the first will be accepted and all others will be rejected.

CRM record association

Each event occurrence must be associated with a CRM record, with the CRM object type defined by the event type schema. The app events API includes multiple fields for associating event occurrence data with CRM records. For all supported CRM objects, it’s recommended to use the objectId field. However, there are some situations where you may want to use the other fields.

utk/email: if you don’t know the contact’s ID, use the utk and/or email field for identification. Providing both of these identifiers also enables you to create and update contacts. For example:
- If utk matches an existing contact but the email doesn’t match, HubSpot will update the contact (by utk) with the new email address.
- If no objectId is provided, the event occurrence will associate with an existing contact that matches the utk/email, or HubSpot will create a new contact if no match is found.
- Note that the utk alone cannot create new contacts. You should always include email with utk to ensure proper association.
domain: for company association, you must provide the objectId, but you can also include domain to update the domain property of that company.

When the email field is provided with other identifiers (objectId, utk), HubSpot will always update the email property on the contact record. For example, if the contact’s email is test@hubspot.com and you send an occurrence with the objectId and email as test-updated@hubspot.com, the contact’s email address property will be updated to test-updated@hubspot.com. Below is the priority order for the CRM record association properties, with the lowest number being the highest priority:

Field	Priority	Description
`objectId`	1	The CRM record ID (recommended).
`utk`	2	The contact usertoken (contacts only).
`email`	3	The contact email address (contacts only).
`domain`	4	The company domain (companies only).

Sending additional data

Beyond sending data to event properties and updating CRM properties via event occurrences, you can include additional data for timeline rendering via the extraData object.

The extraData object can only contain valid JSON. If the JSON is malformed, the occurrence will be rejected and you’ll receive an error response.

extraData field values can be accessed by the event type’s detailTemplate using {{extraData.fieldName}} syntax. All attribute levels of extraData are available through dot notation, such as {{extraData.person1.preferredName}}. For example, the templates below use the customerName and loginLocation property data, along with the surveyData field from extraData sent via the event occurrence. Screenshot showing what the rendering template example below looks like on the contact timeline.

Screenshot showing what the rendering template example below looks like on the contact timeline.

Event occurrence data
Timeline template configuration

{
  "eventTemplateId": "5488733",
  "objectId": "769851",
  "tokens": {
    "customerName": "Tim",
    "loginLocation": "mobileApp"
  },
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

​Sending event occurrences

​CRM record association

​Sending additional data

Sending event occurrences

CRM record association

Sending additional data