Skip to main content
Sitecore Documentation
  • Learn
  • Downloads
  • Changelog
  • Roadmap
CDPCloud Portal
Sitecore CDP Developer Documentation
  • Developing with Sitecore CDP
        • Authentication
        • Base URL
        • Retrieve the browser ID
            • IDENTITY event
            • SEARCH event
            • ADD event
            • ADD event for flights
            • ADD event for ancillary product
            • ADD_CONSUMERS event
            • ADD_CONTACTS event
            • CONFIRM event
            • CONFIRM event for flights
            • CHECKOUT event
            • ORDER_CHECKOUT event
            • CLEAR_CART event
            • PAYMENT event
            • Custom event
        • Sending orders
        • Cart abandonment
        • Send additional event data
        • Troubleshooting
  1. Sending events
  1. Stream API
  3. Direct HTTP requests reference
  5. Sending events
  7. IDENTITY event

IDENTITY event

An IDENTITY event contains data that enables Sitecore CDP to perform identity resolution. When Sitecore CDP receives an IDENTITY event, it runs a linking algorithm to try to match guest data from separate guest profiles, based on your organization's identity rules. We recommend that you learn about identity resolution in Sitecore CDP before you start sending IDENTITY events.

You can pass personally identifiable information (PII) to Sitecore CDP in an IDENTITY event using the following options:

  • To use PII data to perform identity resolution, you must send PII data using the identifiers object. For example, you can use a guest's email address to perform identity resolution. To do this, send the email attribute in the identifiers object. After Sitecore CDP receives the IDENTITY event, it adds the identifiers object to the guest profile, to use for identity resolution in the future.

  • To pass PII data to Sitecore CDP so that it is available as supplementary, additional information in the guest profile, send PII data outside the identifiers object.

You must capture IDENTITY events wherever in the site that the guest provides data that might help identify them. It is common for a single browser session to have multiple IDENTITY events.

To send an IDENTITY event, use the following attributes:

Attribute

Type

Description

Example

Required/optional

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

  • "MOBILE_APP"

  • "MOBILE_WEB"

  • "WEB"

Required

type

string (uppercase)

The type of the event that takes place when the user interacts with your brand.

"IDENTITY"

Required

language

string (uppercase ISO 639-1)

The language the user is using your app in.

  • "DE"

  • "EN"

  • "FR"

Required

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

  • "EUR"

  • "GBP"

  • "USD"

Required

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • "home"

  • "contact-us.html"

Required

pos

string

The name of the point of sale where the interaction with your brand takes place.

  • "myretailsite/ireland"

  • "spinair.com/france"

Required

browser_id

string

The browser ID.

"a38b230c-11eb-4cf9-8d5d-274e9f344925​"

Required

email

string (lowercase recommended)

The email address of the guest.

"[email protected]"

Optional

title

string (title case)

The title of the guest.

"Br", "Brigadier", "Capt", "Colonel", "Dame", "Dr", "Elder", "Fr", "General", "Hon", "Judge", "Lord", "Master", "Miss", "Mr", "Mrs", "Ms", "Mstr", "Prof", "Rabbi", "Rev", "Shaikha", "Sheikh", "Sir", "Sister", "Sr"

Optional

firstname

string (title case recommended)

The first name of the guest.

"Jane"

Optional

lastname

string (title case recommended)

The last name of the guest.

"Doe"

Optional

gender

string

The gender of the guest.

"female"

Optional

dob

string (ISO 8601)

The date of birth of the guest.

"1983-04-15T00:00"

Optional

mobile

string

The mobile number of the guest.

"+3531234567"

Optional

phone

string

The phone number of the guest.

"+3531234567"

Optional

street

array of strings (title case recommended)

The street address of the guest.

["Tara Street"]

Optional

city

string (title case recommended)

The city address of the guest.

"Dublin"

Optional

state

string (title case recommended)

The state address of the guest.

"Oregon"

Optional

country

string (uppercase ISO 3166-1 alpha-2)

The country address of the guest.

"IE"

Optional

postCode

string

The postal code of the guest.

"D2"

Optional

identifiers

array of objects

The identifiers that are used to identify the users of your app.

N/A

Required

The identifiers array of objects:

Attribute

Type

Description

Example

Required/optional

id

string

The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.

"123456"

Required

provider

string

The name of your organization's identity system, external to Sitecore CDP, that provided the unique guest identifier.

"BXLP"

Required

expiry_date

string (ISO 8601)

The date the unique guest identifier expires. This is determined by your organization's identity system.

"2025-04-15T08:39:44.868Z"

Optional

Example 35. IDENTITY event object with identifiers
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "identifiers": [{
        "provider": "BXLP",
        "id": "123456"
    }]
}


Example 36. IDENTITY event object with identifiers and personally identifiable information (PII)
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "identifiers": [
        {
            "id": "123456",
            "provider": "BXLP"
        }
    ],
    "email": "[email protected]",
    "firstname": "Jane",
    "lastname": "Doe"
}


You can pass additional guest data in an event to Sitecore CDP. This new data is compared with existing guests to try and identify the guest. You must capture IDENTITY events wherever in the site the guest provides data that might help identify them. It is common for a single browser session to have multiple IDENTITY events.

To send an IDENTITY event, use the following attributes:

Attribute

Type

Description

Example

Required/optional

channel

string (uppercase)

The touchpoint where the user interacts with your brand.

  • "MOBILE_APP"

  • "MOBILE_WEB"

  • "WEB"

Required

type

string (uppercase)

The type of the event that takes place when the user interacts with your brand.

"IDENTITY"

Required

language

string (uppercase ISO 639-1)

The language the user is using your app in.

  • "DE"

  • "EN"

  • "FR"

Required

currency

string (uppercase ISO 4217)

The alphabetic currency code of the currency the user is using in your app.

  • "EUR"

  • "GBP"

  • "USD"

Required

page

string

The name of the webpage where the interaction with your brand takes place.

This is a custom value of your choice.

  • "home"

  • "contact-us.html"

Required

pos

string

The name of the point of sale where the interaction with your brand takes place.

  • "myretailsite/ireland"

  • "spinair.com/france"

Required

browser_id

string

The browser ID.

"a38b230c-11eb-4cf9-8d5d-274e9f344925​"

Required

email

string (lowercase recommended)

The email address of the guest.

"[email protected]"

Optional

title

string (title case)

The title of the guest.

"Br", "Brigadier", "Capt", "Colonel", "Dame", "Dr", "Elder", "Fr", "General", "Hon", "Judge", "Lord", "Master", "Miss", "Mr", "Mrs", "Ms", "Mstr", "Prof", "Rabbi", "Rev", "Shaikha", "Sheikh", "Sir", "Sister", "Sr"

Optional

firstname

string (title case recommended)

The first name of the guest.

"Jane"

Optional

lastname

string (title case recommended)

The last name of the guest.

"Doe"

Optional

gender

string

The gender of the guest.

"female"

Optional

dob

string (ISO 8601)

The date of birth of the guest.

"1983-04-15T00:00"

Optional

mobile

string

The mobile number of the guest.

"+3531234567"

Optional

phone

string

The phone number of the guest.

"+3531234567"

Optional

street

array of strings (title case recommended)

The street address of the guest.

["Tara Street"]

Optional

city

string (title case recommended)

The city address of the guest.

"Dublin"

Optional

state

string (title case recommended)

The state address of the guest.

"Oregon"

Optional

country

string (uppercase ISO 3166-1 alpha-2)

The country address of the guest.

"IE"

Optional

zip_code

Deprecated. Use postCode.

string (uppercase recommended)

The zip code of the guest.

N/A

Optional

postCode

string

The postal code of the guest.

"D2"

Optional

identifiers

array of objects

The identifiers that are used to identify the users of your app.

N/A

Optional

The identifiers array of objects:

Attribute

Type

Description

Example

Required/optional

id

string

The unique guest identifier provided by your organization's identity system, such as a Customer Relationship Management (CRM) system.

"123456"

Optional

provider

string

The name of your organization's identity system, external to Sitecore CDP, that provided the unique guest identifier.

"BXLP"

Optional

expiry_date

string (ISO 8601)

The date the unique guest identifier expires. This is determined by your organization's identity system.

"2025-04-15T08:39:44.868Z"

Optional

Notice

Your organization either uses the identifiers object or the email attribute to determine the identity of the guest. If your organization uses the email attribute to determine the guest's identity, then the attributes in the identifiers object are ignored. If your organization uses the identifiers attribute to determine the guest's identity, then using the email attribute is optional.

Example 37. IDENTITY event object with identifiers
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home",
    "pos": "myretailsite/ireland",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "identifiers": [{
        "provider": "BXLP",
        "id": "123456"
    }]
}


Example 38. IDENTITY event object with personally identifiable information (PII)
{
    "channel": "MOBILE_APP",
    "type": "IDENTITY",
    "language": "EN",
    "currency": "EUR",
    "page": "home",
    "pos": "spinair.com/france",
    "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
    "email": "[email protected]",
    "title": "Ms",
    "firstname": "Jane",
    "lastname": "Doe",
    "gender": "female",
    "dob": "1980-01-23T00:00",
    "passport_no": "IR123456",
    "mobile": "+3531234567",
    "phone": "+3531234567",
    "street": ["Ashford House", "Tara Street", "Dublin 2"],
    "city": "Dublin",
    "country": "IE",
    "postCode": "D2",
    "identifiers": [{
        "provider": "BXLP",
        "id": "123456"
    }]
}


If you have suggestions for improving this article, let us know!

Documentation Assistant

This assistant uses AI to generate responses based on Sitecore documentation. While it has access to official sources, answers may be incomplete or inaccurate and should not be considered official advice or support.
Powered by
k
kapa.ai
Protected by reCAPTCHA

© Copyright 2026, Sitecore A/S or a Sitecore affiliated company.
All rights reserved.

Privacy policySitecore Trust CenterTerms of use