identityMap vs identity fields: two ways to mark identities in XDM

Why this matters

This matters because inconsistent identity marking leads to incorrect customer matching and fragmented profiles. If identities aren’t properly tagged—whether in identityMap or individual fields—Experience Platform can’t reliably link data across touchpoints, resulting in incomplete or duplicated customer views.

Without a clear primary identity, Real-Time Customer Profile fails to unify data, making segmentation and personalization unreliable. Misaligned namespaces also cause confusion in data ingestion, especially when sources like web SDKs or CRM systems send mixed identity types. This creates risk in campaign targeting and journey optimization, where identity accuracy is essential. Properly defining primary identities and using correct namespaces ensures data aligns correctly and supports actionable insights.

The key ideas

In Adobe Experience Platform, there are two ways to mark identities in a schema: by labeling individual fields as identities using a namespace, or by storing multiple identities in a single field called identityMap. The identityMap approach groups several identities together, grouped by namespace, and is typical when data comes from the Web SDK. This structure supports scenarios where a user has multiple identifiers across different systems, such as email, phone, or user ID.

Marking a field as an identity is more common in CRM-style data, where one clear customer ID defines the record. In such cases, a single identity field with a defined namespace clearly identifies the customer. For both approaches, one identity must be marked as primary. This primary identity is essential for Real-Time Customer Profile to recognize and link the record correctly.

The namespace defines what kind of identifier each value is—such as email or phone number—so Platform knows how to process and match the data. Whether using identityMap or individual identity fields, the use of a primary identity and a namespace ensures accurate identity resolution and consistent customer views across experiences.

How to apply it

When building a schema for customer data from a web session, use identityMap to group multiple identifiers—like email, phone, or user ID—into a single record. This structure is natural when the data comes from a Web SDK, where several identity values are collected and sent together. Each identity in the identityMap is tagged with a namespace, such as "email" or "user_id", to tell Experience Platform what type of identifier it is. This approach supports real-time profile updates by allowing the system to match and merge identities efficiently.

For CRM-style data, where a single customer ID like a customer number or account ID is the main reference, mark that field directly as an identity with a namespace. This is simpler and more intuitive when the data represents a single, authoritative identity. Still, one identity must be designated as primary so it can be used in Real-Time Customer Profile.

In both cases, the namespace defines the identifier type, and a primary identity ensures consistent profile matching. Use identityMap when multiple identities are available, and use field-level identity marking when one clear customer ID dominates the data.

Mistakes to avoid

• Avoid marking multiple identities as primary in the same record. Only one identity should be designated as primary to ensure accurate customer profile alignment in Real-Time Customer Profile. Using multiple primaries can cause data conflicts and inconsistent customer matching.

• Do not rely solely on identityMap without defining a namespace for each identity. Without a namespace, Experience Platform cannot distinguish between different types of identifiers (e.g., email vs. phone). Always assign a namespace to each identity in identityMap to ensure proper identification and integration. Misaligned namespaces lead to identity mismatches and poor data quality.

Quick checklist

• Confirm whether your data source sends one clear customer ID (e.g., CRM record) or multiple identities (e.g., web sessions with various identifiers).
• If multiple identities are present, use identityMap to group them by namespace for consistency and clarity.
• If only one primary identifier exists (like a customer ID from a CRM), mark that field as an identity with a namespace.
• Assign a primary identity in either approach to ensure Real-Time Customer Profile can match and unify data.
• Define the namespace for each identity to specify the type of identifier (e.g., email, phone, user ID) so Experience Platform can interpret it correctly.
• Ensure all identity fields or identityMap entries include a valid namespace to avoid data misalignment.
• Verify that the identityMap or individual identity field is properly structured to match the schema expectations in AEP.
• Double-check that the primary identity is explicitly marked to prevent profile matching failures.