Overview

The Identify event method allows you to tie events occurring on your digital properties to a specific, known user via the user providing an email, name or personally-identifiable information (PII) to you.

The best times to trigger an Identify call are typically:

When a user first registers or creates an account with you
When a user logs back in to their account
When a user updates their profile information, e.g. an address or email.

There may also be times you want to trigger an Identify call, even on an anonymous user, in order to gather a user’s cookie-based IDs so they can be passed into downstream vendors like CDPs or data warehouses.

How It Works

Identify events need to be added to your website’s code wherever you’d like it to be fired. The function you will add to your website looks like this:

analytics.identify("sample_user_id", {
  name: "Jane Doe",
  email: "[email protected]",
  last_login: "2024-01-26T22:54:45.961Z"
});

This call could produce the below payload, with common fields removed:

{
  "type": "identify",
  "traits": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "last_login": "2024-01-26T22:54:45.961Z"
  },
  "userId": "sample_user_id"
}

With common fields, the event could look like this:

{
    "timestamp": "2024-01-27T00:13:54.846Z",
    "integrations": {},
    "userId": "matt@metaourter",
    "anonymousId": "f8cc0f85-cb4d-4f73-b16f-c251384fdf74",
    "type": "identify",
    "traits": {
        "name": "Jane Doe",
        "email": "[email protected]"
				"last_login": "2024-01-26T22:54:45.961Z"
    },
    "context": {
        "page": {
            "path": "/shop",
            "referrer": "https://www.example.com/",
            "search": "",
            "title": "metashop",
            "url": "https://demo.metarouter.io/shop?"
        },
        "providers": {},
        "globalPrivacyControl": false,
        "consent": {
            "optOut": {
                "C0001": false,
                "C0002": false,
                "C0003": false,
                "C0004": false,
                "C0005": false
            }
        },
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "locale": "en-US",
        "library": {
            "name": "analytics.js",
            "version": "npm:next-1.51.3-mr.3"
        }
    },
    "messageId": "8d2a01c2425435f48271ea7297772e10",
    "writeKey": "example_writekey",
    "sentAt": "2024-01-27T00:13:54.850Z",
    "_metadata": {
        "bundled": [],
        "unbundled": [],
        "bundledIds": []
    }
}

Identify events contain two fields specific to this type of call:

Field	Required?	Data Type	Description
`userId`	Optional, but recommended whenever calling Identify	String	A unique identifier that you recognize within your database.
`traits`	Optional	Object	Dictionary of fields that describe the user.

User ID Best Practices

Because Identify calls are typically made when a user provides PII to you, you should always include a User ID in your call that represents a permanent, unique identifier for the user. This means that it should never be an email or username as those may change over time. PII should instead be sent as traits and stored alongside the User ID within your user database.

Traits

Traits help describe useful details about a user, like their PII, demographics, or type of account they have with your business.

This is a list of common traits for Identify events. We recommend using these whenever one of these fields covers what you are trying to track.

Trait	Data 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	User’s birthday
`company`	Object	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. We recommend 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 we automatically fill 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 Marketing”
`username`	String	User’s username. This should be unique to each user.
`website`	String	Website of a user

Additional traits may also be included to support scenarios where the above traits are insufficient to cover a given use case.