There's a new version of the HubSpot API

As of November 30, 2022, HubSpot API keys are no longer a supported authentication method for accessing HubSpot APIs. Instead, you should use a private app access token or OAuth to authenticate API calls. Learn more about this change and how to migrate an API key integration to use a private app instead.

Create or update a timeline event

Last updated May 15, 2023

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

Method Details

HTTP Methods:

PUT

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, or update an existing 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.