Timeline API v1 to v3 Migration

Important: As of December 11, 2020, the Timeline Events API v3 is available only for apps that create immutable events. Immutable events cannot be modified or deleted after their creation. If your app currently updates or deletes events, please continue to use the v1 API.

Why is it important?

Migrating to the new API will enable customers to interact with integrator data throughout the HubSpot platform.

Marketers measure their effort’s contribution to revenue, conversion, and other key goals.

By using HubSpot Timeline API V3 for events data, developers can enable their customers to interact with their data through attribution reporting, custom reports, automation and more - you can make sure your App Events are valued as part of that customer journey!

This data can then be leveraged in a host of downstream features, so users can see the full value of their investment, and your app's contribution.

It's important to note that this is a work in progress. Our current plan is that these events can be used within automated workflows as triggers, within custom reports, and as sources for attribution reporting, when these features become available.

Currently, the Timeline Events V3 API supports immutable events only.

We encourage all app partners / developers, with immutable events data, to start using Timeline Events V3 API to have your events tied into HubSpot’s attribution reporting, custom report, and automation through workflows. 

In the future!

We will be adding mutable events into our Timeline API.

Until then developers with mutable event data should remain on Timeline API V1.

HubSpot will be focused on expanding the number of features that leverage your event data including displaying on timelines, complex filtering, list creation & more

The following table outlines a few of the ways in which integrator events will be able to be used once sent through V3 of the Timeline API with more forthcoming soon. This list will continue to expand in the months to come.

HubSpot Tool

Customer Impact

Custom Report Builder

Enables flexible custom report building and visualization across dozens of HubSpot and Integrator data sources (including v3 events)

Attribution Reporting

Enable customers to customize which parts of the customer journey are included in their attribution models.

Workflows

Enable customers to build workflows that are triggered by specific event instances sent via the Timeline API v. 3 (these function to “delay until event happens” actions). In the future, these events will also be able to trigger enrollment in a workflow.

List Segmentation

Enable customers to create custom static or active lists that leverage events sent through the Timeline API v3 as filters. This is a work in progress

Note: All listed benefits may not be available at the same time, as features will be rolled out in staged releases.

Please share your feedback here to let us know your experience in this process of moving from V1 to V3 of HubSpots Timeline API.

Additional Resources:

For more details about the v3 API endpoints, please see the V3 API Reference

Overview of changes

Events are read-only

There are no endpoints to update a single event or group of events (as exist in v1). If you need to modify your timeline events, then you should stay on v1 for the moment.

Naming changes

Some terminology has changed between v1 and v3:

  • "Event types" in v1 are called "Event templates" in v3
  • "Event properties" in v1 are called "Event tokens" in v3.

URL changes

The base URL of the timeline API has changed from integrations/v1/<<appId>>/timeline/ to crm/v3/timeline/<<appId>>

The following URL path elements have also changed:

  • event-types ==> event-templates
  • properties ==> tokens
  • event ==> events

Payload changes

The payload of the API requests have had some changes:

  • The field eventTypeId has changed to eventTemplateId
  • Properties were flat in the request in v1. In v3, tokens are in the tokens object field
  • No need for applicationId in the payload in v3 calls.

Examples

Below are examples of all the different API calls that can be made to the timeline API. For each example, there is a v1 example, and a v3 equivalent which should highlight the changes in the API.

Create Event Type

v1

curl -X POST -H "Content-Type: application/json" -d '
{ 
    "name" : "Email received by contact", 
    "applicationId": <<appId>>
}' \
'https://api.hubapi.com/integrations/v1/<<appId>>/timeline/event-types?hapikey=<<developerAPIkey>>'

v3

curl -X POST -H "Content-Type: application/json" -d '
{ 
  "name": "Email received by contact", 
  "objectType": "contacts"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'

Get Event Type

v1

curl -X GET 'https://api.hubapi.com/integrations/v1/<<appId>>/timeline/event-types?hapikey=<<developerAPIkey>>'

v3

curl -X GET 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'

Define Event Properties

v1

curl -X POST -H "Content-Type: application/json" -d '
{
    "name" : "emailSubject",
    "label" : "Email subject",
    "propertyType": "String"
}' \
'https://api.hubapi.com/integrations/v1/<<appId>>/timeline/event-types/<<eventTypeId>>/properties?hapikey=<<developerAPIkey>>'

v3

curl -X POST -H "Content-Type: application/json" -d '
{
  "name": "emailSubject",
  "label": "Email subject",
  "type": "string"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerAPIkey>>'

Get Event Properties

v1

curl -X GET -H "Content-Type: application/json" 'https://api.hubapi.com/integrations/v1/<<appId>>/timeline/event-types/<<eventTypeId>>/properties?hapikey=<<developerAPIkey>>'

v3

curl -X GET -H "Content-Type: application/json" 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerAPIkey>>'

Defne Templates

v1

curl -X PUT -H "Content-Type: application/json" -d '
{
    "id": <<eventTypeId>>,
    "applicationId": <<appId>>,
    "name": "Email received by contact",
    "headerTemplate": "Received email ''",
    "detailTemplate": "Email received at {