Spec: Identify

The Segment Identify call 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 the user, like their email, name, and more.

Segment recommends that you make an Identify call:

• After a user first registers
• After a user logs in
• When a user updates their info (for example, they change or add a new address)

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

Calling Identify in one of Segment’s libraries is one of the first steps to getting started with Segment. Refer to library-specific documentation for more details.

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

{
  "type": "identify",
  "traits": {
    "name": "Peter Gibbons",
    "email": "peter@example.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@example.com",
  plan: "premium",
  logins: 5
});

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

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@example.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"
}

Create your own Identify call

Use the following interactive code pen to see what your Identify calls would look like with user-provided information:

Sample output goes here!

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 to 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—Segment recommends UUIDs.

Here’s an example of a JavaScript event for an anonymous user:

analytics.identify({
  subscriptionStatus: 'inactive'
});

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.

Segment recommends 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.

Custom traits

Custom 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.

Segment has reserved some custom traits that have semantic meanings for users, and will handle them in special ways. For example, Segment always expects email to be a string of the user’s email address. Segment sends this on to destinations like Mailchimp that require an email address for their tracking.

Reserved custom traits Segment has standardized:

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. Keep in mind that not all destinations support these reserved traits, so sending these traits in camelCase and snake_case can result in two sets of traits in other destinations.