# Identify

The `identify` call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them 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 their latest traits are captured.

## When should I call `identify`?

Ideally, you should call `identify` 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, for example) require an initial identify call to know who the user is when they first start the session.

## Sample payload

A sample payload for the `identify` event after removing the common fields mentioned in the [**Common Fields**](https://rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/common-fields/) section is as shown:

```javascript
{
  "type": "identify",
  "traits": {
    "name": "Name Surname",
    "email": "sample@example.com"
  },
  "userId": "hashed_user_id"
}
```

The corresponding event that generates the above payload via the JavaScript SDK is as shown:

```javascript
rudderanalytics.identify("hashed_user_id", {
  name: "Name Surname",
  email: "sample@example.com",
})
```

## Identify fields

The `identify` call has the following fields in addition to the [**Common Fields**](https://rudderstack.com/docs/rudderstack-api/api-specification/rudderstack-spec/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. |

## User ID vs Anonymous ID

RudderStack requires every `identify` call to have either a `userId` or an `anonymousId`. This section highlights the difference between the two.

### User ID

A user ID (`userId`) uniquely identifies your user present in your database. It is a permanent identifier of your customer which never changes - like a database ID.

For `identify` calls, you should include a `userId` as often as possible to identify the most up to date traits of the customer.

We strongly recommend using a database ID as the `userId` instead of usernames or email addresses. This is because the user may update their username or email address at any point in the future. Instead, you can 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, you can use 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](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/) 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 bits of user information included in an `identify` call. Some example of traits include age, gender, or some specific details, e.g. if a user has a premium or a basic plan.

RudderStack has some reserved traits that it handles in special ways. These are listed in the table below:

| **Trait**     | **Type** | **Description**                                                                                                                                                                                                                                                                                      |
| ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | String   | User's unique ID.                                                                                                                                                                                                                                                                                    |
| `firstName`   | String   | User's first name.                                                                                                                                                                                                                                                                                   |
| `lastName`    | String   | User's last name.                                                                                                                                                                                                                                                                                    |
| `name`        | String   | Full name of the user. If you have 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   | <p>User's street address. This can optionally contain either/all of the following fields:</p><ul><li><code>city</code></li><li><code>country</code></li><li><code>postalCode</code></li><li><code>state</code></li><li><code>street</code></li></ul>                                                 |
| `birthday`    | Date     | User's date of birth.                                                                                                                                                                                                                                                                                |
| `company`     | Object   | <p>User's company. This can optionally contain either/all of the following fields:</p><ul><li><code>name</code> (String)</li><li><code>id</code> (String / Number)</li><li><code>industry</code> (String)</li><li><code>employee\_count</code> (Number)</li><li><code>plan</code> (String)</li></ul> |
| `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 at all, as it handles these destination-specific conversions automatically.

## Passing traits to an `identify` call

RudderStack lets you pass traits to an `identify` call. These traits will be stored in a cookie on your browser or mobile device and will be passed automatically to all the subsequent calls.

An example of how you can pass traits to an `identify` call from our [**JavaScript SDK**](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/rudderstack-javascript-sdk/) is shown in the following code snippet. You can check our other [**SDKs**](https://rudderstack.com/docs/stream-sources/rudderstack-sdk-integration-guides/) for more examples.

```javascript
rudderanalytics.identify("user-id", {
  name: "username",
  gender: "male",
})
```

In the above example, `{name: "username", gender: "male"}` are the traits stored in a cookie and passed along all the subsequent calls.

## Contact us

For queries on any of the sections covered in this guide, you can [**contact us**](mailto:%20docs@rudderstack.com) or start a conversation in our [**Slack**](https://rudderstack.com/join-rudderstack-slack-community) community.