Identify
Get started with the RudderStack Identify API call.
The identify
call allows you to identify a visiting user and associate their actions to that identity. It also lets you record traits about the user like their name, email address, etc.
As a best practice, make sure identify
is called at the start of every session or page load for logged-in users, if possible. This will ensure all the latest traits are captured.
When should I call identify?
Ideally, you should make an identify
call in the following scenarios:
- After a user registers on your website or app
- After a user logs in to your site or app
- When a user updates their information, e.g., residential address, email ID
- When you load a page accessible by a logged-in user: Although this is optional, many tools (such as Intercom) require an initial
identify
call to know who the user is at the session start.
Sample payload
Here is a sample payload for an identify
event after removing Common fields:
{
"type": "identify",
"context": {
"traits": {
"name": "Richard Hendricks",
"email": "rhedricks@example.com",
"logins": 2
}
},
"userId": "27340af5c8819"
}
The corresponding event that generates the above payload via the JavaScript SDK is:
rudderanalytics.identify("27340af5c8819", {
name: "Richard Hendricks",
email: "rhedricks@example.com",
logins: 2
})
Identify fields
The identify
call has the following fields in addition to the Common fields:
Field | Type | Presence | Description |
---|
userId | String | Optional, if anonymousId is set | Your user’s unique identifier. Every identify call requires a userId or an anonymousId . |
traits | Object | Optional | Includes the traits of the user such as their name , email , etc. For more more information, check the Traits section below. |
The field names can change slightly depending on the SDK. However, the functionality remains the same.
See the SDK-specific documentation for the implementation specifics and details on the above fields.
User ID vs Anonymous ID
RudderStack requires every identify
call to have either a userId
or an anonymousId
. This section highlights the differences between the two.
User ID
A user ID (userId
) uniquely identifies your user in your database. It is a permanent identifier of your customer which never changes - like a database ID.
For identify
calls, include a userId
as often as possible to identify the most up to date traits of the customer.
It is recommended to use a database ID as the userId
instead of usernames or email addresses. This is because users may update their username or email address at any point in the future. Instead, pass these attributes as traits.
Anonymous ID
There are instances where you may get a visitor on your website/app who may or may not be your customer. Nonetheless, you still want to track their actions and tie them to various events, page views, and traits. In such cases, you should use an Anonymous ID (anonymousId
) to identify this user.
An anonymousId can be any identifier. For instance, a session ID corresponding to the visitor’s session. If you don’t have a readily available identifier, we recommend generating a UUID.
RudderStack’s web and mobile
SDKs automatically use anonymous IDs to track unknown users on your website or mobile apps, so you don’t have to worry about including an
anonymousId
explicitly.
Identify traits
Traits are additional user information included in an identify
call. Some examples of traits include age, gender, or some specific details - for example, a user’s product plan (basic, premium, and so on).
There are some differences in the way RudderStack captures and sends the user traits across different SDKs. While RudderStack ideally sends the user traits in the context.traits
object (as in case of JavaScript SDK), for some SDKs it also sends the user traits in the root-level traits
object (for backward compatibility).
Refer to the SDK-specific documentation for more details on sending user traits.
After making an identify
call, user traits are not required in subsequent calls. You only need to include changed/updated traits since the last identify
call.
RudderStack has some reserved traits that it handles in special ways. These are listed in the table below:
Trait | Type | Description |
---|
id | String | Fallback parameter used only for mapping data if userId is not available in the event payload. |
firstName | String | User's first name |
lastName | String | User's last name |
name | String | Full name of the user. If you already passed the firstName and lastName , RudderStack will automatically fill this field. |
age | Number | User's age |
email | String | User's email address |
phone | String | User's phone number |
address | Object | User's street address. This can optionally contain either/all of the following fields: city country postalCode state street
|
birthday | Date | User's date of birth |
company | Object | User's company. This can optionally contain either/all of the following fields: name (String)id (String / Number)industry (String)employee_count (Number)plan (String)
|
createdAt | Date | Date of user's account creation. We recommend using the ISO-8601 date string format. |
description | String | User's description |
gender | String | User's gender |
title | String | User's title related to their position in their company |
username | String | User's username. This should be unique for every user. |
website | String | User's website |
avatar | String | URL of the user's avatar image |
Different destinations recognize some of the above traits differently. For example, Mixpanel recognizes createdAt
as $created
, while Intercom recognizes it as created_at
.
With RudderStack, you don’t have to worry about these inconsistencies, it handles these destination-specific conversions automatically.
Passing traits to an identify call
When you pass traits to an identify
call, they will be stored in a cookie on the user’s browser or mobile device and will be passed automatically to all subsequent calls.
Below is an example of how to pass traits to an identify
call from our JavaScript SDK. For more examples, check our other SDKs.
rudderanalytics.identify("27340af5c8819", {
name: "Richard Hendricks",
gender: "male",
})
In the above example, {name: "Richard Hendricks", gender: "male"}
are stored in a cookie and passed along with all subsequent calls.
Questions? Contact us by email or on
Slack