Skip to main content
Last modified: November 18, 2025
This feature requires approval from HubSpot to use. If you’re interested in applying to get access to app events, 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 event data following the event type’s defined schema along with the fullyQualifiedName value in a eventTypeName field.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
}

Fields marked with * are required.

FieldTypeDescription
eventTypeName*StringThe fully qualified name of the event type, which you’ll use to identify the event via the API. This value is automatically set by HubSpot and can be obtained via the API after creating the event type. This value cannot be changed after creation.
objectId*StringThe 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.
objectTypeFullyQualifiedNameTypeThis 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.
emailStringFor contact association, you can provide the email address of the contact to associate. Learn more about CRM record association.
utkStringFor contact association, you can provide the usertoken of an existing contact to associate. Learn more about CRM record association.
domainStringInclude this field in addition to objectId to set the company’s domain property value. Learn more about CRM record association.
timestampStringSets 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.
propertiesObjectKey-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.
extraDataObjectAdditional information which will be available to timeline rendering templates. Must be in valid JSON format.
timelineIFrameObjectWhen included, the timeline card will include a hyperlink that allows users to open the linked contents in an iframe. Learn more about using iframes.
idStringA 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, 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:
FieldPriorityDescription
objectId1The CRM record ID (recommended).
utk2The contact usertoken (contacts only).
email3The contact email address (contacts only).
domain4The 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.
  • 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"
      }
    ]
  }
}