Using identityMap in Data Collection

The identityMap payload object is how you tell the Edge Network who a visitor is beyond their device-level ECID. When a visitor signs in, completes a purchase, or otherwise becomes known, you can send person-level identifiers (CRM ID, hashed email, loyalty ID, etc.) alongside the ECID. These person-level identifiers provide valuable information to downstream services so that they can:

This page covers how to construct identityMap payloads, choose the right settings for each identity, and handle common implementation scenarios.

Payload structure structure

The identityMap is a JSON object where each top-level key is a namespace and the value is an array of identity descriptors. You can include one or more namespaces in a single payload, and each descriptor contains three fields: id, authenticatedState, and primary.

{
  "identityMap": {
    "CRMID": [
      {
        "id": "abc-123-xyz",
        "authenticatedState": "authenticated",
        "primary": true
      }
    ]
  }
}

The sections below cover each part of the payload in detail.

Namespace keys namespace-keys

Each top-level key in identityMap is an identity namespace — a string that classifies the type of identifier (for example, CRMID, Email, Phone, or LoyaltyId). Namespaces must exist in Identity Service before you reference them in a payload. You can include multiple namespace keys in the same event when you have more than one identifier for the visitor.

You do not need to include the ECID as a namespace key. The Edge Network automatically adds the ECID to the identity payload. If you do include the ECID explicitly, do not mark it as primary when a person-level identity is also present.

id id

The id field is the identifier string itself — the value that tells Experience Platform which specific person or device this identity represents. Each identity namespace expects a specific value format, and sending a value in the wrong format creates a distinct identity that cannot be merged with the correctly formatted version, resulting in fragmented profiles.

Before you include a value in identityMap, prepare it according to the format that your target namespace expects:

For the full list of standard namespaces and their definitions, see Identity namespace overview.

Collecting id at runtime collect-id

The identifier you need is rarely available directly on the page. Common collection strategies include:

authenticatedState authenticated-state

The authenticatedState field tells downstream services how much trust to place in a given identity. The following values are valid for this field:

primary primary-identity

Every identityMap payload must have exactly one identity marked as primary: true. The primary identity determines which identity is used as the anchor for the event in Experience Platform.

Follow these guidelines when setting the primary identity:

{
  "identityMap": {
    "CRMID": [
      {
        "id": "abc-123-xyz",
        "authenticatedState": "authenticated",
        "primary": true
      }
    ],
    "Email": [
      {
        "id": "user@example.com",
        "authenticatedState": "authenticated",
        "primary": false
      }
    ]
  }
}

Sending identityMap in your implementation send-identity

alloy("sendEvent", {
  xdm: {
    identityMap: {
      CRMID: [
        {
          id: "abc-123-xyz",
          authenticatedState: "authenticated",
          primary: true
        }
      ]
    },
    eventType: "web.webpagedetails.pageViews"
  }
});

Common scenarios common-scenarios

{
  "identityMap": {
    "CRMID": [
      {
        "id": "abc-123-xyz",
        "authenticatedState": "authenticated",
        "primary": true
      }
    ]
  }
}

{
  "identityMap": {
    "CRMID": [
      {
        "id": "abc-123-xyz",
        "authenticatedState": "loggedOut",
        "primary": false
      }
    ]
  }
}

{
  "identityMap": {
    "CRMID": [
      {
        "id": "abc-123-xyz",
        "authenticatedState": "authenticated",
        "primary": true
      }
    ],
    "Email_LC_SHA256": [
      {
        "id": "a1b2c3d4e5f6...",
        "authenticatedState": "authenticated",
        "primary": false
      }
    ],
    "LoyaltyId": [
      {
        "id": "LOY-98765",
        "authenticatedState": "authenticated",
        "primary": false
      }
    ]
  }
}

How identityMap affects the identity graph identity-graph

Every identityMap payload that reaches Experience Platform is processed by Identity Service, which links the identities you send into an identity graph. Which namespaces you include, how you set authenticatedState, and which identity you mark as primary, directly shape how Identity Service builds and merges those graphs.

Key behaviors to be aware of:

If your implementation uses identity graph linking rules (such as namespace priority or the identity optimization algorithm), review the implementation guide to understand how those rules interact with the identities you send through identityMap.