Skip to main content
POST
/
integrators
/
timeline
/
v3
/
events
Send event data (single)
curl --request POST \
  --url https://api.hubapi.com/integrators/timeline/v3/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "eventTemplateId": "1001298",
  "email": "art3mis-pup@petspot.com",
  "tokens": {
    "petName": "Art3mis",
    "petAge": 3,
    "petColor": "black"
  },
  "extraData": {
    "questions": [
      {
        "question": "Who's a good girl?",
        "answer": "Bark!"
      },
      {
        "question": "Do you wanna go on a walk?",
        "answer": "Woof!"
      }
    ]
  },
  "timelineIFrame": {
    "linkLabel": "View Art3mis",
    "headerLabel": "Art3mis dog",
    "url": "https://my.petspot.com/pets/Art3mis",
    "width": 600,
    "height": 400
  }
}
EOF
{
  "objectType": "contacts",
  "id": "petspot:1001298:art3mis-pup@petspot.com-004",
  "eventTemplateId": "1001298",
  "email": "art3mis-pup@petspot.com",
  "objectId": "28001",
  "timestamp": "2020-01-30T17:42:10.276Z",
  "tokens": {
    "petName": "Art3mis",
    "petColor": "black",
    "petAge": "3"
  },
  "extraData": {
    "questions": [
      {
        "question": "Who's a good girl?",
        "answer": "Bark!"
      },
      {
        "question": "Do you wanna go on a walk?",
        "answer": "Woof!"
      }
    ]
  },
  "timelineIFrame": {
    "linkLabel": "View Art3mis",
    "headerLabel": "Art3mis dog",
    "url": "https://my.petspot.com/pets/Art3mis",
    "width": 600,
    "height": 400
  }
}

Supported products

Requires one of the following products or higher.
Marketing HubMarketing Hub -Free
Sales HubSales Hub -Free
Service HubService Hub -Free
Content HubContent Hub -Free
Data HubData Hub -Free

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

The timeline event definition.

The state of the timeline event.

​
eventTemplateId
string
required

The event template ID.

​
tokens
object
required

A collection of token keys and values associated with the template tokens.

​
domain
string

The event domain (often paired with utk).

​
email
string

The email address used for contact-specific events. This can be used to identify existing contacts, create new ones, or change the email for an existing contact (if paired with the objectId).

​
extraData
object

Additional event-specific data that can be interpreted by the template's markdown.

​
id
string

Identifier for the event. This is optional, and we recommend you do not pass this in. We will create one for you if you omit this. You can also use {{uuid}} anywhere in the ID to generate a unique string, guaranteeing uniqueness.

​
objectId
string

The CRM object identifier. This is required for every event other than contacts (where utk or email can be used).

​
timelineIFrame
object
Example:
{
  "linkLabel": "View Art3mis",
  "headerLabel": "Art3mis dog",
  "url": "https://my.petspot.com/pets/Art3mis",
  "width": 600,
  "height": 400
}
​
timestamp
string<date-time>

The time the event occurred. If not passed in, the curren time will be assumed. This is used to determine where an event is shown on a CRM object's timeline.

​
utk
string

Use the utk parameter to associate an event with a contact by usertoken. This is recommended if you don't know a user's email, but have an identifying user token in your cookie.

Response

successful operation

The current state of the timeline event.

​
eventTemplateId
string
required

The event template ID.

​
id
string
required

Identifier for the event. This should be unique to the app and event template. If you use the same ID for different CRM objects, the last to be processed will win and the first will not have a record. You can also use {{uuid}} anywhere in the ID to generate a unique string, guaranteeing uniqueness.

​
objectType
string
required

The ObjectType associated with the EventTemplate.

​
tokens
object
required

A collection of token keys and values associated with the template tokens.

​
createdAt
string<date-time>

Unused.

​
domain
string

The event domain (often paired with utk).

​
email
string

The email address used for contact-specific events. This can be used to identify existing contacts, create new ones, or change the email for an existing contact (if paired with the objectId).

​
extraData
object

Additional event-specific data that can be interpreted by the template's markdown.

​
objectId
string

The CRM object identifier. This is required for every event other than contacts (where utk or email can be used).

​
timelineIFrame
object
Example:
{
  "linkLabel": "View Art3mis",
  "headerLabel": "Art3mis dog",
  "url": "https://my.petspot.com/pets/Art3mis",
  "width": 600,
  "height": 400
}
​
timestamp
string<date-time>

The time the event occurred. If not passed in, the curren time will be assumed. This is used to determine where an event is shown on a CRM object's timeline.

​
utk
string

Use the utk parameter to associate an event with a contact by usertoken. This is recommended if you don't know a user's email, but have an identifying user token in your cookie.

Last modified on December 16, 2025