Spec: Identify

identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them like their email, name, etc.

Our recommendation for when and how often you should call identify is as follows:

  • After a user registers
  • After a user logs in
  • When a user updates their info (eg changes or adds a new address)
  • Upon loading any pages that are accessible by a logged in user (optional)

The first three examples are pretty self-explanatory, but many might ask: why you would call identify on every page load if we’re storing the userId in the cookie?

Let’s imagine this scenario:

I log into your app. Identify is called. For whatever reason, I close the browser and don’t return until later. There’s no way of knowing where I will reenter your app from. I could start my session from anywhere. And because there are many tools out there that require an initial identify call for certain features (e.g. Intercom chat widget) it’s important to tell your end tools who the user is when they first start their session.

Calling identify in one of our libraries is one of the first steps to getting started with Segment.

Here’s the payload of a typical identify call with most common fields removed:

{
  "type": "identify",
  "traits": {
    "name": "Peter Gibbons",
    "email": "peter@initech.com",
    "plan": "premium",
    "logins": 5
  },
  "userId": "97980cfea0067"
}

And here’s the corresponding Javascript event that would generate the above payload:

analytics.identify("97980cfea0067", {
  name: "Peter Gibbons", 
  email: "peter@initech.com", 
  plan: "premium", 
  logins: 5
});

Beyond the common fields, an identify call has the following fields:

FieldTypeDescription
traits optionalObjectFree-form dictionary of traits of the user, like email or name.

See the Traits field docs for a list of reserved trait names

userId requiredStringUnique identifier for the user in your database

A userId or anonymousId is required

See the Identities docs for more detail

Example

Here’s a complete example of an identify call:

{
  "anonymousId": "507f191e810c19729de860ea",
  "channel": "browser",
  "context": {
    "ip": "8.8.8.8",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.115 Safari/537.36"
  },
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Salesforce": true
  },
  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
  "receivedAt": "2015-02-23T22:28:55.387Z",
  "sentAt": "2015-02-23T22:28:55.111Z",
  "timestamp": "2015-02-23T22:28:55.111Z",
  "traits": {
    "name": "Peter Gibbons",
    "email": "peter@initech.com",
    "plan": "premium",
    "logins": 5,
    "address": {
      "street": "6th St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94103",
      "country": "USA"
    }
  },
  "type": "identify",
  "userId": "97980cfea0067",
  "version": "1.1"
}

Identities

The identify call specifies a customer identity that you can reference across the customer’s whole lifetime. Every identify call must have a User ID or an Anonymous ID, depending on how much you know about the user in question.

Anonymous ID

There are certain cases where you don’t actually know who the user is according to your database, but you still want to be able tie them to traits, events or page views. For example, you may not know who a user is when tracking newsletter signups or anonymous page views.

In these cases, you should use an Anonymous ID.

The Anonymous ID can be any pseudo-unique identifier. For example, on your servers you can use a session id. If you don’t have any readily available identifier, you can always generate a new random one—we recommend UUIDs.

Note: Our browser and mobile libraries automatically use Anonymous IDs under the covers to keep track of users as they navigate around your website or app, so you don’t need to worry about them when using those libraries.

User ID

User IDs are a more permanent and robust identifier, like a database ID. Since these IDs are consistent across a customer’s lifetime, identify calls should include a User ID as often as possible.

A User ID is usually the unique identifier that you recognize a user by in your own database. For example, if you’re using MongoDB it might look something like 507f191e810c19729de860ea.

We recommend using database IDs instead of simple email addresses or usernames, because database IDs never change. That guarantees that even if the user changes their email address, you can still recognize them as the same person in all of your analytics tools. And even better, you’ll be able to correlate analytics data with your own internal database.

Instead of using an email address or a username as a User ID, send them along as traits.

Traits

Traits are pieces of information you know about a user that are included in an identify call. These could be demographics like age or gender, account-specific like plan, or even things like whether a user has seen a particular A/B test variation. Up to you!

We’ve reserved some traits that have semantic meanings for users, and we handle them in special ways. For example, we always expect email to be a string of the user’s email address. We’ll send this on to destinations like Mailchimp that require an email address for their tracking.

You should only use reserved traits for their intended meaning.

Reserved traits we’ve standardized:

TraitTypeDescription
addressObjectStreet address of a user optionally containing: city, country, postalCode, state or street
ageNumberAge of a user
avatarStringURL to an avatar image for the user
birthdayDateUser’s birthday
createdAtDateDate the user’s account was first created

We recommend ISO-8601 date strings, but also accept Unix timestamps for convenience.

descriptionStringDescription of the user
emailStringEmail address of a user
firstNameStringFirst name of a user
genderStringGender of a user
idStringUnique ID in your database for a user
lastNameStringLast name of a user
nameStringFull name of a user

If you only pass a first and last name we’ll automatically fill in the full name for you.

phoneStringPhone number of a user
titleStringTitle of a user, usually related to their position at a specific company

Example: “VP of Engineering”

usernameStringUser’s username

This should be unique to each user, like the usernames of Twitter or GitHub.

websiteStringWebsite of a user

Note: You might be used to some destinations recognizing special traits by slightly different names. For example, Mixpanel recognizes a $created trait when the user’s account was first created, while Intercom recognizes the same trait as created_at instead. Luckily, you don’t have to worry about those inconsistencies. Just pass us createdAt. We’ll handle all of the destination-specific conversions for you automatically. Same goes for the rest of the reserved traits.

You can pass these reserved traits using camelCase or snake_case, so in Javascript you can match the rest of your camel-case code by sending firstName, while in Ruby you can match your snake-case code by sending first_name. That way the API never seems alien to your code base.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!