How to create Deal timeline event?

[eddynguyen99]

Hi! I'm trying to create a new Deal timeline event. I have created the type in the Timeline panel.

This is what I've tried and the current problem:

PUT URL: https://api.hubapi.com/integrations/v1/:aplicationId/timeline/event

Headers:

- Content-Type: application/json

- Authorization: Bearer :accessToken

Content:

{
  "id": "0c353fde-4a1c-4330-8c2d-becf08521861", // random uuid
  "email": "contact@email.com", // email of a contact in my connected app
  "eventTypeId": 123456 // Deal timeline event ID in the app
}

When I make this request, I have the following back with status 400:

{
  "status": "error",
  "message": "Deal id must be provided. Creation is not supported at the moment.",
  "correlationId": "e41e0bc8-b1bc-40fe-ba88-2ef294b2f5ff",
  "requestId": "84de58fc9fe1d429cc8317493e277867"
}

I'm confused by the message, does this mean I have to provide deal id ( and if so, what would be the key of this field )? Or does it mean I cannot create deal timeline event via API call? Or both?

I can't seem to find anything in the documentation about creating Deal timeline event.

For what it's worth, the same call with the eventTypeId of a Contact timeline event works! I would love some pointers and/or link to documentation please!

[Derek_Gervais]

Hey @eddynguyen99 ,

Whenever you create a timeline event, you need to include a field (usually an ID) to identifiy the HubSpot object (contact, company, deal) that the timeline event will be associated with. For timeline events that are associated with a contact, you can choose to include the contact vid, or the contact's email address property. Including the contact's email address also allows for the added functionality that, in the event that no contact with that email address currently exists in HubSpot, a new contact record will be created. This is why the request you've included works just fine when you're creating timeline events for contact objects.

Timeline events that are associated with deals are more limiting; you must include a vaild Deal ID, and deal creation based on new timeline events is not supported. This means that in order to create a timeline event for a given deal, the following must be true:

1. That deal must already exist in HubSpot; if it doesn't, you need to create it
2. You must have that deal's ID; if you don't, you need to get it.
   1. If you've just created the deal based on step 1 above, the response will have the deal ID.
   2. If you're trying to get a deal associated with a specific contact, you can use the CRM Associations API.

Regarding the docs; the Timeline API docs can be a bit dense. The passage that discusses creating timeline events for deals is in section 6 of this doc:

In addition to working with contacts, it's also possible to create event types for companies and deals. For those event types, you must use objectId to associate the event with the company or deal. For companies, the objectId must be set to the companyId of the company you want to associate the event with, and for deals you would set the objectId to the dealId of the deal record.