Event Method: Identify


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/ 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:

FieldRequired?Data TypeDescription
userIdOptional, but recommended whenever calling IdentifyStringA unique identifier that you recognize within your database.
traitsOptionalObjectDictionary 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 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.

TraitData TypeDescription
addressObjectStreet address of a user optionally containing: citycountrypostalCodestate, or street
ageNumberAge of a user
avatarStringURL to an avatar image for the user
birthdayDateUser’s birthday
companyObjectCompany the user represents, optionally containing: name (String), id (String or Number), industry (String), employee_count (Number) or plan (String)
createdAtDateDate the user’s account was first created. We recommend using ISO-8601 date strings.
descriptionStringDescription of the user
emailStringEmail address of a user
firstNameStringFirst name of a user
genderStringGender of a user
idStringUnique ID in your database for a user
lastNameStringLast name of a user
nameStringFull name of a user. If you only pass a first and last name we automatically fill in the full name for you.
phoneStringPhone number of a user
titleStringTitle of a user, usually related to their position at a specific company. Example: “VP of Marketing”
usernameStringUser’s username. This should be unique to each user.
websiteStringWebsite of a user

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