You're in the right place! Segment documentation is now part of Twilio Docs. The content you are used to is still here—just in a new home with a refreshed look.

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 and name.

Segment University: The Identify Method

Check out the high-level overview of the Identify method in Segment University. (You must be logged in to access.)

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)

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

For example, here's the payload of a typical Identify call with most common fields removed:

1{
2  "type": "identify",
3  "traits": {
4    "name": "Peter Gibbons",
5    "email": "peter@example.com",
6    "plan": "premium",
7    "logins": 5
8  },
9  "userId": "97980cfea0067"
10}

Here's the corresponding JavaScript event that would generate the above payload:

1analytics.identify("97980cfea0067", {
2  name: "Peter Gibbons",
3  email: "peter@example.com",
4  plan: "premium",
5  logins: 5
6});

(information)

Info

Based on the library you use, the syntax in the examples might be different. You can find library-specific documentation on the Sources Overview page.

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

Field		Type	Description
`traits`	optional	Object	Free-form dictionary of traits of the user, like `email` or `name`. See the Custom traits section for a list of reserved trait names.
`userId`	required; optional if `anonymousID` is set instead	String	Unique identifier for the user in your database. A `userId` or an `anonymousId` is required. See the Identities docs for more details.

(information)

Info

Note that these traits coming in from your source events are called custom traits.

Example

Here's a complete example of an Identify call:

1{
2  "anonymousId": "507f191e810c19729de860ea",
3  "channel": "browser",
4  "context": {
5    "ip": "8.8.8.8",
6    "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"
7  },
8  "integrations": {
9    "All": false,
10    "Mixpanel": true,
11    "Salesforce": true
12  },
13  "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db",
14  "receivedAt": "2015-02-23T22:28:55.387Z",
15  "sentAt": "2015-02-23T22:28:55.111Z",
16  "timestamp": "2015-02-23T22:28:55.111Z",
17  "traits": {
18    "name": "Peter Gibbons",
19    "email": "peter@example.com",
20    "plan": "premium",
21    "logins": 5,
22    "address": {
23      "street": "6th St",
24      "city": "San Francisco",
25      "state": "CA",
26      "postalCode": "94103",
27      "country": "USA"
28    }
29  },
30  "type": "identify",
31  "userId": "97980cfea0067",
32  "version": "1.1"
33}

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 UUIDv4 format.

(information)

Info

Segment's website and mobile libraries automatically use Anonymous IDs 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.

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

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

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, User IDs might look something like this: 507f191e810c19729de860ea.

Segment recommends using database IDs, in uuidv4 format, instead of email addresses or usernames because database IDs never change. This 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 you'll be able to correlate analytics data with your own internal database.

(success)

Success!

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

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.

(warning)

Warning

Only use reserved traits for their intended meaning.

Reserved custom traits Segment has standardized:

Trait	Type	Description
`address`	Object	Street address of a user optionally containing: `city`, `country`, `postalCode`, `state`, or `street`
`age`	Number	Age of a user.
`avatar`	String	URL to an avatar image for the user.
`birthday`	Date	The user's birthday.
`company`	Object	The company the user represents, optionally containing: `name` (String), `id` (String or Number), `industry` (String), `employee_count` (Number) or `plan` (String)
`createdAt`	Date	Date the user's account was first created. Segment recommends using ISO-8601 date strings.
`description`	String	Description of the user.
`email`	String	Email address of a user.
`firstName`	String	First name of a user.
`gender`	String	Gender of a user.
`id`	String	Unique ID in your database for a user.
`lastName`	String	Last name of a user.
`name`	String	Full name of a user. If you only pass a first and last name, Segment automatically fills in the full name for you.
`phone`	String	Phone number of a user.
`title`	String	Title of a user, usually related to their position at a specific company. Example: "VP of Engineering"
`username`	String	User's username. This should be unique to each user, like the usernames of Twitter or GitHub.
`website`	String	Website of a user.

(information)

Info

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. Segment attempts to handle all the destination-specific conversions for you automatically. If you need help understanding if a specific field will be converted to a destination, take a look at Segment's open source integration code, view the destination's documentation, or contact Segment support.

You can pass these reserved traits using camelCase or snake_case. For example, in JavaScript you can match the rest of your camelCase code by sending firstName, while in Ruby you can match your snake-case code by sending first_name. This keeps the API consistent 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.