There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Create a timeline event

Last updated January 7, 2025

POST /integrations/v1/:application‐id/timeline/event

Please note: beginning December 2024, the following changes will be made to the v1 Integration Timeline API.

  • You will not be able to update existing events.
  • You cannot use the PUT method to create events.

You can now use the POST method to create events, however it's recommended to transition to the v3 Timeline Events API for the most up to date features. Learn more about this update on the HubSpot Developer Changelog.

Method Details

HTTP Methods:

POST

Content Type:

application/json

Response Format:

json

Requires Authentication?

Yes

Rate Limited?

Yes

Headers

User-Agent

Products:

Marketing & CRM

Required Scope:

timeline

Create a new event.

Please see the Timeline Overview for more details about creating events.

Required Parameters How to use Description
OAuth Access Token Authorization: Bearer {token}
Used in the request headers

Used to authenticate the request. Please see this page for more details about authentication.
application-id Used in the request URL The ID of the application that the event type was created for.  The eventTypeId used in the request body must line up with this application-id.
 id Used in the request body

The ID of the event you're creating.  You will need to specify your own event ID when creating an ID, it will not be assigned automatically.

Using the ID of an existing event will update the existing event.

Please note that the ID must be unique across all accounts for a given eventTypeId
 eventTypeId Used in the request body The event type that you're creating. This must line up with the application-id in the request URL.

Events must include at least one identity parameter to be associated with a contact record. See the overview and the examples to the right for more details.

Identity Parameters How to use Description
objectId Used in the request body The vid of the contact you're adding the event to.
email Used in the request body The email of the contact you're adding the event to.
utk Used in the request body The usertoken of the contact you're adding the event to.

Optional Parameters How to use Description
extraData Used in the request body An object containing extra data for the event, that can be displayed in the event details. See the examples to the right and the description on the overview for more details.
timelineIFrame Used in the request body

If included, the event will display a link that will open an IFrame. This is an object that must have the following fields:

  • linkLabel - The text used to display the link that will display the IFrame.
  • iframeLabel - The label of the modal window that displays the IFrame contents.
  • iframeUri - The URI of the IFrame contents.
  • width - The width of the modal window.
  • height - The hight of the modal window.

See the Timeline Extensions feature from the overview for more details.
Any custom properties. Used in the request body You can set up custom properties for your event, and include values for those properties when creating or updating the event. See the description on the overview for more details.

See the JSON examples for more details for including custom properties or extra data.

Returns a 204 response on success. Otherwise, you'll receive a 4xx error, with more details about the specific error in the body of the response.

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
Example PUT URL, creating events for app ID 6543: https://api.hubapi.com/integrations/v1/6543/timeline/event Example JSON data: An example with the minimum fields required to create a new event: { "id":"3", "objectId":1, "eventTypeId":"123" } You can use the email or utk of a record in place of the contact vid, like the following: { "id":"3", "email":"test@test.com", "eventTypeId":"123" } { "id":"3", "utk":"89b5afb740d41f4cd6651ac5237edf09", "eventTypeId":"123" } If you provide an objectId and email, or the utk and email, the email for the contact will be updated to the email that was passed with the event. This example updates the email address of the contact with vid '11': { "id":"1", "objectId":11, "email":"santa.claus@far.com", "eventTypeId":"123" } Event with some extra data (note that extra data is not a string, it's part of the object sent in): { "id":"3", "objectId":1, "eventTypeId":"123", "extraData":{ "name":"JohnDoe", "weather":"Cloudy" } } If event type 123 has a numeric property called presentationId, the following would also be a valid JSON to send for that event type: { "id":"3", "objectId":1, "eventTypeId":"123", "presentationId":"9876543", "extraData":{ "name":"JohnDoe", "weather":"Cloudy" } } Notice how, even though presentationId is a numeric property, data has to come in as string. You can include timelineIFrame to allow your event to show an IFrame containing data from another system. This example would include a link with the text 'View external data' that when clicked would show a modal window contaning an IFrame for the page at 'https://www.example.com': { "id":"3", "objectId":1, "eventTypeId":"123", "timelineIFrame": { "linkLabel": "View external data", "iframeLabel": "Example iframe", "iframeUri": "https://www.example.com", "width": 800, "height": 300 } }
import requests import json # This token must be generated using the OAuth flow prior to using this API. OauthToken = 'XXXX' url ='https://api.hubapi.com/integrations/v1/189139/timeline/event' headers = {} headers['Content-Type']= 'application/json' headers['Authorization']= 'Bearer'+' '+ OauthToken data={ "id":"3", "objectId":1, "eventTypeId":"123", "timelineIFrame": { "linkLabel": "View external data", "iframeLabel": "Example iframe", "iframeUri": "https://www.example.com", "width": 800, "height": 300 } } put_data = json.dumps(data) r = requests.put(data=put_data, url=url, headers=headers) print(r.status_code)