Get started with the RudderStack Identify API call.
6 minute read
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, for example, residential address, email ID, etc.
(Optional) When you load a page accessible by a logged-in user. This is required only when you have a downstream tool with such requirement (for example, Intercom).
Sample payload
Here is a sample payload for an identify event after removing Common fields:
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).
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 ifuserId 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.
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.