Posting Timeline Events

You can post timeline events to a contact via our API.

POST https://driftapi.com/contacts/timeline

Required Scope: contact_write

Timeline events take the following form, and should be included in the post body:

{
  "contactId": long,
  "createdAt": long (optional),
  "externalId": string (optional, see callout below),
  "event": string,
  "attributes": { // deprecated
    string: object,
    ...
  }
}

Attributes are lists of key/value pairs, where each value is "stringified", or converted to its string representation, if it's not a string already.

If successful, added timeline events will show up here (as well as added attributes to to the event) in the contact record.

It's recommended that you add your app name in the event.

Example Format:

{
  "contactId": 1115142980,
  "createdAt": 1546344000000,
  "event": "New External Event from <your app>"
}

// Note that the createdAt time can be excluded from the payload (will default to the time of send).

🚧

A note on the createdAt field

The createdAt field is the current timestamp epoch time in milliseconds. The above timestamp 1546344000000 for example is 1/1/2019 12:00:00 GMT.

A response back of 200 with the added event object indicates successful receipt. Note that the event type string will be converted to lower case in the timeline view.

📘

But I want to use my identifier (externalId) instead of the Drift ID.

To use an externalId for contact lookup and posting, provide your "externalId" value in the payload and leave the contactId field absent. The timeline event should post in the same way if there's a contact match to your external identifier.

This should appear in the contacts profile on the contact's timeline afterwards.

You can also split users into separate audiences or segments based on the presence (or absence) of particular timeline events. These segments could then be used for targeting the next time one of these user's visits your website!