HTTP API: Attributes and Events

Updated 5 days ago ​by Matt Bilotti

The Drift REST API makes it dead simple to track events and customer information. Send your customer data through this API and Drift can become intelligent. We’ll identify what makes a healthy user and empower you to become context-driven when communicating with customers.

What is Drift?

Drift is a customer communication platform that makes it much easier for you and your team to understand, support, and engage with your customers.

Methods

The following are a collection of easy-to-use HTTP methods that you can use to pass information to Drift from any application that can make requests to them.

POST

https://event.api.drift.com/identify

This method is used to identify users or companies based on their unique id in your company’s tables.

Body

{
  "orgId":1,
  "userId":"019mr8mf4r",
  "attributes":{
    "companyId":"a234mrf",
    "name":"John Doe",
    "email":"john.doe@gmail.com",
    "startDate":"1441981033123",
    "plan":"free",
    "revenue":100.0
  },
  "createdAt":"1441981033123"
}

or

{
  "orgId":1,
  "companyId":"a234mrf",
  "attributes":{
    "name":"Doe's Donuts",
  },
  "createdAt":"1441981033123"
}
orgId
number
The id of your organization in Drift
userId
string, number
The unique user ID in your user table for the user.
companyId
string, number
The unique company ID in your company table for the company.
attributes
Object (optional)
A dictionary of attributes you know about this user, such as their emailnamecompany. We strongly suggest that you pass the email attribute.
createdAt
number (optional)
The unix timestamp in milliseconds that the event was created at. We will fill it in with the time we receive the event if you do not pass it.
The attributes object must be a flat object. Nested objects or arrays will not work.

See Special Attributes for information on attribute that we treat differently than custom attributes.

Special Attributes

Special Attributes are attributes that have a defined meaning for users or companies, and will be handled differently if they exist. For example, we always expect the name attribute to contain the user’s full name, and we will populate or update the user’s name in our system to reflect that.

In order to create a new, custom attribute, you can just code it into your body, you do not need to define the attribute anywhere!

You should only use these attributes for their intended meaning.

User Special Attributes

email
string
This is the email of the user, and is used to pull in other information on a user
name
string
This the user’s name. We use it to fill in the name of the user in our systems
companyId
string, number
This is the id of a company in your system. This should match up with a company id that you have already called with the identify call. We use this to map the user to the company.
startDate
number, string
This is the date the user started being a customer. This needs to be a unix timestamp in milliseconds.
revenue
number
This is the revenue that this user is generating. It can be over any time period as long as you stay consistent. Currently, we assume that this number is in USD.

Company Special Attributes

name
string
This the company’s name.
description
string
This is a short description of the company.
location
string
This the company’s location.
logo
string
This is a URL to the company’s logo.
phone
string
This the company’s phone number.


POST

https://event.api.drift.com/identify/multi

This method is used to make bulk uploads of user information to Drift. It works exactly like the /identify endpoint, except that you can pass a list of identities instead of making one request for each one. This is method is currently limited to 600 identify objects.

Body

[
  {
    "orgId":1,
    "companyId":"a234mrf",
    "attributes":{
      "name":"Doe's Donuts",
    },
    "createdAt":"1441981033123"
  },
  {
    "orgId":1,
    "userId":"019mr8mf4r",
    "attributes":{
      "companyId":"a234mrf",
      "name":"John Doe",
      "email":"john.doe@gmail.com",
      "startDate":"1441981033123",
      "plan":"free",
      "revenue":100.0
    },
    "createdAt":"1441981033123"
  },
  ...
]

POST

https://event.api.drift.com/track

This method is what you call to send an event to Drift. All events are named and can have a list of attributes attached. You can send an event to Drift for companies or users by passing either the userId or the companyId.

Body

{
  "orgId":1,
  "userId":"019mr8mf4r",
  "event":"Link Clicked",
  "attributes":{
    "linkUrl":"http://www.example.com"
  },
  "createdAt":"1441981033123"
}
orgId
number
The id of your organization in Drift
userId
string, number
The unique user ID in your company’s user table for the user.
companyId
string, number
The unique company ID in your company table for the company.
event
string
This is the name of this type of event. You should try to reuse the same events with different properties to describe similar actions such as Share or Link Clicked
attributes
Object, optional
A dictionary of attributes about this type of event, such as shareType or linkUrl.

createdAt
number, optional
The unix timestamp in milliseconds that the event was created at. We will fill it in with the time we receive the event if you do not pass it.

The attributes object must be a flat object. Nested objects or arrays will not work.

Special Events

There are some event names that we have reserved because they mean something specific to our customers, and we treat these events differently. Some of these events also have special attributes that go along with them. Below is a list of them.

You should only use special events for their intended meaning.

Page events — page*

Any event that begins with page will be treated as a Page event. Page events should be fired when a user lands on a specific page.

Special Attributes

name
string
The name of the page that the user has landed on, such as Homepageor Login Page
url
string
The url of the page that the user has landed on

POST

https://event.api.drift.com/track/multi

This method is used to make bulk uploads of events to Drift. It works exactly the same as the /trackendpoint except that you can pass a list of events instead of just one. This is currently limited to 600 track objects.

Body

[
  {
    "orgId":1,
    "userId":"019mr8mf4r",
    "event":"Link Clicked",
    "attributes":{
      "linkUrl":"http://www.example.com"
    },
    "createdAt":"1441981033123"
  },
  ...
]

Not using Drift yet? Get your free account here.


Was this article helpful?


Can’t find what you’re looking for?

Talk To Us