Every MoEngage workspace already merges anonymous and registered profiles automatically on login. Refer to Anonymous to Registered User Merge for that always-on behavior. Use this article instead if you want to merge profiles on identifiers beyond the default ID such as email, mobile number, or up to five custom attributes, across Data APIs, SDKs, file imports, and integrations like Shopify.
The two mechanisms have different rules: this feature is opt-in and irreversible once activated; the anonymous-to-registered merge is always-on. Both transfer all events with no cap.

Overview

Users interact with your brand across channels such as website, app, offline store, social login. Each channel can generate a separate profile for the same person. The Identity Resolution feature of MoEngage merges these profiles into one, using identifier attributes such as ID, Email, or Mobile Number from data ingested via Data APIs, MoEngage SDKs, or CSV files. This gives you one accurate view of each user for segmentation, personalization, and reporting.

PrerequisitesTo use identity resolution, choose an existing user attribute as an identifier (like a phone number or email ID) that uniquely identifies the user and activate it as an identifier. Only Admins can access this setting.

Use Cases

Identity resolution plays a critical role in the following scenarios:

Online-to-offline matching: A user browses your site with their email, then completes a purchase in-store using their phone number. Identity Resolution links both records to the same person.
Multiple sign-in methods: A user registers via email, mobile OTP, and Facebook login, each creating a separate profile. Identity Resolution consolidates them into one as more identifiers are collected.

Configure Multiple Identifiers

You can configure up to five identifiers per workspace. ID is the default and always active; at least one identifier must remain active at all times.
You can opt to configure other user attributes, such as email and mobile number, as additional identifiers. For example, if you choose email ID and mobile number as identifiers, MoEngage checks the email ID and mobile number for all users. In cases where multiple users share the same mobile number but have distinct email IDs, the system consolidates those users into a single profile as one of the identifier values matches successfully.
When two profiles share the value of any active identifier, MoEngage merges them. If profiles have conflicting data, the retained profile wins and the merged profile is deleted after its events and attributes transfer over.

Perform the following steps to configure multiple identifiers in the MoEngage dashboard (Only Admins can view and access Identity resolution):

On the left navigation menu in the MoEngage dashboard, go to Settings > Data > Identity resolution.
On the Identity resolution page, click +Add identifier(s). You can add up to five identifiers for identity resolution.
Choosing good identifiersA good identifier uniquely identifies one person (not a shared household phone or generic support email), stays consistently available across every data source you plan to use it with (SDK, API, file imports), and won’t be reused across different people over time. Picking the wrong identifier is the most common source of unexpected merges or profiles that fail to merge.
1. By default, ID is listed as an identifier for merging user profiles using identity resolution. The Active tag represents the identifier currently used for identity resolution for merging users in your current workspace.
2. All the identifiers added are listed on this page. Click the ellipsis icon ( ) to perform the following:
  - Pause identity resolution: This option allows you to pause merging the user based on that identifier.
  - View/Edit exceptions: This option allows you to view or edit exceptions of that identifier. In the View/Edit exception dialog box, select the exception from the list and click Save.
The Merge settings option takes you to Step 2: Review merge rules.
On the Add identifier(s) page, you can perform the following steps:

Step 1: Select Identifiers

Screenshot 2025-02-17 at 11.33.59 AM.png

Select the checkbox next to the User attributes you want to select as identifiers for identity resolution.
You can view the Description for each attribute.
Exceptions: Null and blank values are always excluded from identity-matching process and cannot be edited or removed. You can add further exceptions in string format.
You can view the various Data sources from which these identifiers are obtained. Identifiers backed by more data sources make for more reliable matching, check the Data sources before selecting.
The Tracked data types denote the various data types for which the data for that attribute has been tracked in MoEngage so far.
- Only string type attributes can be identifiers; other types are converted to string automatically.
- Identity-matching process uses exact string values.
Click Next.

Case SensitivityIdentifier matching is case-sensitive and does no normalization. If the same value can arrive in different cases across sources (e.g. an email captured as John@brand.com on web and john@brand.com via CSV import), those profiles won’t merge unless you standardize casing before ingestion.

Step 2: Review Merge Rules

Profile retention rules: This rule decides which user profile survives a merge, and are evaluated in order. Perform the following steps to add profile retention rules:

In the Rule 1 list, select a user attribute. If only one of the two profiles has data for that attribute, that profile is retained. If both profiles have data for it, Rule 1 can’t break the tie and Rule 2 runs instead. Rule 1 is optional and is empty by default.
In the Rule 2 list, select a user behavior. This is the tiebreaker rule and defaults to Latest Last Seen. Whichever profile matches the behavior is retained.

For example, consider you have two customer profiles for the same user in which Profile 1 is received online, and Profile 2 is received offline.

Scenario	General Rule	Profile 1 (Online)	Profile 2 (Offline)	Outcome
Rule 1 decides	The profile with data in the selected attribute is considered the retained profile.	Rule 1 = Email ID, name, email, mobile — all populated	ID, name, mobile, no email	Profile 1 is retained: it’s the one with data in the Rule 1 attribute (Email).
Rule 1 ties, Rule 2 decides	When both profiles have data in the selected attribute, Rule 1 fails (ties), and Rule 2 is validated to break the tie.	Rule 1 = Email Rule 2 = Latest Last Seen ID, name, email, mobile, first seen — all populated	ID, name, email, mobile, first seen — all populated	Both profiles have Email, so Rule 1 ties. Rule 2 retains whichever profile has the more recent “last seen” timestamp.

Attribute rules: This rule controls how specific custom attributes combine on merge. You can add a maximum of five such rules.
Perform the following steps to add your own custom user attribute rules:
1. Click Add rule.
2. Select User attributes and Merge rules. For example, consider you have two customer profiles for the same user in which Profile 1 is received online, and Profile 2 is received offline. Each profile has a Loyality_points attribute and has data in it, and if you want the SUM of both Loyality_points when both these profiles are merged, perform the following:
  1. Select Loyality_points in User attribute list.
  2. Select Sum of values in Merge rules list. So, whenever user profiles are merged, the resulting profile comprises the combined sum of both profiles’ loyality points. LTV ships with Sum of values pre-configured, no setup needed.
The Verify merge section shows how users are merged based on the profile retention and attribute rules you configured. Select I have verified all merge scenarios checkbox after verifying the merge scenarios.
Click Next.

Whenever new data is ingested for an existing user, MoEngage automatically updates the existing user profile and their properties. Profile retention rules applied only during a merge.

Step 3: Activate Identity Resolution

This step provides the instructions to be considered before and after activating the identity resolution.

Irreversible changes to be considered before activating.

A user merged cannot be unmerged.
For 48 hours post activation, the following actions are not possible on the Identity resolution page:
- Adding new identifiers
- Pausing/re-activating identifiers, and editing exceptions
- Changing Merge settings
The Merge User API is disabled when Identity Resolution is enabled.

After activating identity resolution:

Existing users in the workspace merge over 48 hours
New incoming users merge with existing users based on profile retention rules

Merge Caps:

Only the first 50 users in your workspace with the same identifier value are merged, rest remains un-merged.
If a new user is ingested sharing an identifier value already held by 50 merged users, that user is still created, but the identifier value itself is dropped from their profile and won’t participate in future merges.
Any update sent to a user who remains unmerged past the cap is dropped in the same way.
To raise the 50-user cap for your workspace, contact your MoEngage Customer Success Manager (CSM) or the Support team.

Screenshot 2025-02-19 at 11.51.05 AM.png

Select By activating identity resolution, I understand the impact of merging the user check box and click Activate to activate identity resolution.

Data Ingestion Support

MoEngage supports multiple identifiers across every ingestion path: Data APIs, SDKs, file imports, and native integrations like Shopify.

Data APIs
SDK
File Imports
Shopify

Data APIs (Track User, Create Event, Bulk Import) can create or update users using any active identifier, not just ID.
You can create a Server-to-Server user with no ID at all, as long as another identifier is present.

Request Body

The following is a sample cURL request for a Bulk Import API consisting the User and Event payloads:

User payload must contain at least one configured identifier in attributes.
Event payload must include identifiers inside user_identifiers as shown in the below example where moe_mobile is one of the identifiers in the workspace

"user_identifiers":{
"moe_mobile":"{{Mobile_Number}}"
}

Sample cURL Request for Bulk Import API:

The following Bulk Import API consists of payloads for both users and events.cURL

curl --location 'https://api-xx.moengage.com/v1/transition?app_id=O7NIHY0AT1K1FL8DR1J1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization\_Key}}' \
--data '{
    "type": "transition",
    "elements": [
      {
      "type": "customer",
      "attributes": {
        "moe_mobile": "{{Mobile_Number}}",
        "first_name": "John"
      }
   },
{
      "type": "event",
      "user_identifiers": {
         "moe_mobile": "{{Mobile_Number}}"
     },
     "actions": [
       {
      "action": "AddToCart",
      "attributes": {
          "product": "MacBook Air",
          "Brand": "Apple"
       }
    }
   ]
  }
 ]
}'

Pre-Flight Checklist for S2S User Creation

Before sending S2S requests with multiple identifiers, confirm:

All identifiers you intend to send are configured as active identifiers in Settings > Data > Identity resolution.
Requests include the full set of configured identifiers rather than a partial subset wherever possible, to avoid ambiguous matches.
Profile retention rules are configured to reflect which data source (online vs. offline, primary system vs. secondary) should win in a conflict.
You have a process to handle API error responses for merge conflicts rather than silently retrying.
Merges triggered this way are irreversible, test in a staging workspace before rolling out to production.

Cross-Profile Identifier Matching

A single ingested payload can carry identifier values that already belong to different existing users. For example, the id in the payload may match User A while moe_mobile matches User B. In these cases:

All matching profiles merge into a single profile. There is no identifier priority order and no “first match wins” logic — every existing profile that matches on any active identifier is pulled into the merge.
The merge is automatic. The request is not rejected, and it is not queued for manual review.
The retained profile’s values are decided by your configured profile retention rules. With the default Latest Last Seen tiebreaker, the incoming request typically becomes the most recent activity, so its identifier values are retained.

ExampleAssume id, email, and moe_mobile are all active identifiers, and the default profile retention rule (Latest Last Seen) applies.Existing state:

User 1: id = ID1, email = E1
User 2: id = ID2, email = E2, moe_mobile = M2

Incoming payload: id = ID3, email = E1, moe_mobile = M2The new payload matches User 1 on email and User 2 on moe_mobile. Both merge together with the incoming record, producing:

Merged User: id = ID3, email = E1, moe_mobile = M2

ID3 and the incoming values win because the new request has the most recent last-seen timestamp. ID1, ID2, and E2 are dropped.

Cross-profile identifier matching works the same way across every Data API (Track User, Create Event, Bulk Import) and across all other ingestion paths — SDKs, file imports, and native integrations such as Shopify. The merge is driven by your Identity Resolution configuration, not by which API or source the data arrived on.

Because a single request can collapse two or more existing profiles, review your profile retention and attribute merge rules carefully before activating Identity Resolution. Merges cannot be reversed.

Partial Identifier Payloads

When a Data API call includes only a subset of the identifiers configured for your workspace — for example, the workspace has id, moe_email, and moe_mobile active, but the request only carries moe_mobile — MoEngage treats the call as a straightforward user update, not a merge.

Lookup: MoEngage searches for an existing user using whatever identifiers are present in the request (moe_mobile in the example above).
Update: Every attribute in the request payload is written to the matched profile. Identifier values not included in the request are left untouched on the existing profile.
No merge: Because only one profile is resolved, no profile retention or attribute merge rules are evaluated. This differs from Cross-Profile Identifier Matching above, where multiple existing profiles collapse into one and retention rules decide which values survive.

A partial identifier payload does not cause data loss on its own — attributes outside the request are preserved on the existing profile. Data loss only happens when a payload’s values overwrite existing values for the same attribute, which is standard update behavior across all ingestion paths.

Supported SDKs:

Android (13.6.00)
iOS (9.23.0)
WebSDK (2.52.2)
GTM
AMP
ReactNative
Flutter
Capacitor

identifyUser() function is introduced in the new SDK versions that are compatible with Identity resolution. This function is a direct replacement of the SetUniqueID function and allows you to track users with multiple identifier attributes. Make sure to configure these identifiers in MoEngage before IdentifyUser function is implemented.The following are examples of SDK sample codes where email and id are set as identifiers in a given workspace.

Sample Codes

MoEAnalyticsHelper.identifyUser(context, "android-native-uid")
MoEAnalyticsHelper.identifyUser(
 context,
 mapOf(
  "email" to "android@moengage.com",
  "id" to "android"
 )
)

MoEngageSDKAnalytics.sharedInstance.identifyUser(identity: "ios-native-uid")
MoEngageSDKAnalytics.sharedInstance.identifyUser(identities: [
 "email": "ios@moengage.com",
 "id": "ios"
 ])

Moengage.identifyUser({
  uid: 'uid1',
  u_em: 'email1@someEmail.com'
})

ReactMoE.identifyUser("react-native-uid");
ReactMoE.identifyUser({
 "id": "react-native",
 "email": "react-native@moengage.com"
})

final MoEngageFlutter _moengagePlugin = MoEngageFlutter(WORKSPACE_ID);
_moengagePlugin.identifyUser("flutter-uid");
_moengagePlugin.identifyUser({
 "email": "flutter@moengage.com",
 "id": "flutter"
})

Updates are made to SDK functions to improve user identification and session management.

Forced Logout: The MoEngage SDK no longer automatically logs out the previous user when a new user is detected on the device. Logout should now be explicitly called for workspaces enabled with Identity resolution to avoid data corruption.
SetUniqueID: IdentifyUser function supports multiple identifiers, which replaces the need of using SetUniqueID function for user identification. Note that SetUniqueID is marked for removal in the future releases of SDK versions - it is important to use identifyUser instead especially if you are using Identity resolution in your workspace.
SetAlias: For workspaces with the Identity resolution feature enabled, MoEngage SDK stores the previous identifier values. When IdentifyUser function is used to track the new identifier values, MoEngage SDK detects the change in identifier value and reports accordingly.

Retrieving Linked Profiles Programmatically Use the asynchronous getter getUserIdentities() to check, client-side, which identifiers are bound to the current local session. It queries local SDK storage and returns a JSON dictionary of all currently bound identifier keys and values.

Run getUserIdentities() before an explicit user logout to confirm which identifiers are linked, and avoid breaking active device identity links.

You can view the multiple identifiers configured for your workspace in the following sections:

User Imports in Segment

If you have configured multiple identifiers for a given workspace, you can see them in the Map identifiers section in Step 2 while creating new user imports, otherwise you can only see ID.
For Anonymous user import, if an identifier user attribute is selected as an anonymous ID, the users from the import may merge with the existing users having the same identifier value. For example, if you have configured an email ID as an identifier and, while mapping identifiers, you choose an email ID as the anonymous ID, there is a chance that users from the import may merge with other users having the same email ID.

The uploaded CSV must have at least one column matching a configured identifier.
After activating new identifiers, update existing periodic imports to map them correctly.

Data Imports in Data

If you have configured multiple identifiers for a given workspace:

While creating a new user data import, you can view them in the Map identifiers section, otherwise you can only see ID.
While creating a new event data import, you can view them in Step 2: Import configuration and action under the Map identifiers section, otherwise you can only see ID and Event time.
While creating new auxiliary data imports, you can view them in Step 2: Import configuration and action by turning on the Update user profile attributes (optional) toggle of the Map identifiers section, otherwise you can only see ID..

File Import & Segment CSV Processing Rules

CSV uploads fully respect your active Identity Resolution configuration with the following behavior:

Multi-key ingestion: if a row contains values for more than one active identifier (e.g. both email and mobile), MoEngage checks both against existing records. If a single row bridges two distinct profiles, a background merge triggers immediately.

Set Up Identifiers

PrerequisiteContact your CSM to enable Identity Resolution for your workspace.

You can configure a maximum of five identifiers to merge users in MoEngage. Based on your business requirements, specify the identifiers.

Handle Existing Duplicate Users

MoEngage executes a one-time script to merge the existing users in the workspace based on the identifers you have activated as well as the merge settings selected in your workspace.When Identifiers are activated, a support ticket is raised where the feature enablement is tracked. The feature is enabled from the backend to activate the identifiers and start merging existing users based on the set identifiers. A report is generated once the feature is enabled, which will indicate every user merge action that is executed. This can be provided by the support team upon request.This section describes how you can use MoEngage Identity Resolution in Shopify.

PrerequisiteEnsure that Shopify is integrated with MoEngage and that the Email-id or mobile number is configured as the identifier for profile merge.

Scenario 1: Email-id as the Identifier

A user uses their email ID to register themselves on Shopify or purchase a product through your application.When the user clicks Check Out:

A cart token for that order is generated which regularly updates every time you make a new purchase.
The user is no longer treated as anonymous after they provide their email ID and other details during product purchase.

In this scenario, consider three instances when a user browses your application with different email IDs as described below:

Instance 1:

Anonymous user U1 adds items to the cart, provides an email ID as Demo@gmail.com, and converts to a registered user. A cart token (C1) is generated.

Instance 2:

Anonymous user U2 adds items to the cart, provides an email ID as Demo2@gmail.com, and converts to a registered user. A cart token (C2) is generated.

Instance 3:

Anonymous user U3 adds items to the cart, provides an email ID as Demo@gmail.com and merges their profile with U1. A cart token (C3) is updated.Because you have configured email ID as the identifier, MoEngage identifies that User 1 and User 3 share the same Email-id and merge their profiles.You can find all user events in the MoEngage dashboard at Segment > User Profile > Activity Info.

Scenario 2: Mobile number as the Identifier

A user registered with your website with their email ID and provided their mobile number during the order transaction. The next time the user visits your offline store and provides the same mobile number during product purchase.

User1 registers online using a mobile number (M1) on Shopify and does some activity on the website.
User2 visits an offline store and provides a mobile number (M1) during product purchase. Offline data is then uploaded to MoEngage using CSV imports. In such cases, MoEngage identifies that User 1 and User 2 share the same mobile number and merge their profiles.

Impact of Merging Users

Merging affects data, segments, campaigns, and triggers internal system events. Review each before activating.

On Data
On Segments
On Campaigns
On System Events
On Reachability

User attribute info: the retained profile’s attributes win; any attribute missing from the retained profile is filled in from the merged profile.
Devices: all devices from both profiles carry over to the retained profile, no device data is lost.
Events: Events from the merged profile transfer to the retained profile, including for transitive multi-ID merges (a user merging into a profile that has itself already been merged).

System-Generated Merge Events

When automated Identity Resolution consolidates duplicate profiles, MoEngage fires internal system events depending on the scenario.

MOE_USER_MERGE_EVENT: fires globally whenever a standard profile merge starts.
MOE_USER_MERGED: fires on the primary (retained) profile once data fields combine successfully.
MULTI_ID_USER_MERGED: fires only when a multi-identifier configuration resolves and collapses multiple records

In short, a regular single-identifier merge fires MOE_USER_MERGE_EVENT and MOE_USER_MERGED. A multi-ID merge fires all three, including MULTI_ID_USER_MERGED.

Hidden by DefaultMULTI_ID_USER_MERGED visibility is OFF by default, so it won’t appear in Segment or Flow event dropdowns. To expose it, go to Settings > Data Management > User Events and toggle its visibility ON.


Channel	Reachability Attribute	Merge Outcome
Email	Hard bounce	If multiple users getting merged have the same email ID but conflicting hard bounce values, the outcome is hard Bounce = true. If users getting merged have different email IDs, the retained user’s email preferences remains post-merge.
	Spam	If multiple users getting merged have the same email ID but with conflicting Spam statuses, the outcome is Spam = true. If multiple users getting merged have different email IDs, the retained user’s Spam status is retained.
	Unsubscribe	If multiple users getting merged have the same email ID but with conflicting Spam statuses, the outcome is Unsubscribe = true. If multiple users are getting merged and have different email values, the retained user’s Unsubscribe status is retained.
	Subscription Categories	Subscription categories of retained users are retained.
Push	Reachability push status code (iOS, Android, Web)	When users are merged, all devices are added to the retained user. Final Reachability is derived based on all devices present with the retained user.
SMS	Subscription status	Retained user’s mobile number preferences is retained.
WhatsApp	Subscription status	Retained user’s mobile number preferences is retained.

FAQs

Some user attributes and events seem to be lost during merge. Is it possible?

Yes.

Example 1: If two users merge on a shared identifier but have a different attribute value, the merged profile only retains the value based on the retention rules. Hence, one of the attribute values is lost.
Example 2: If two users merge on a shared mobile number but have different emails, the merged profile’s email is lost — only the retained profile’s email survives.

You should set the profile retention rules deliberately to control this. Merges cannot be reversed.

The user count and MTU numbers have suddenly reduced after activating identity resolution. Why?

One of the profiles is deleted when two profiles merge into one. This reduces your key metrics, such as Total users, MTU, MAU, and more.Note that every unmerged duplicate profile counts separately toward your Monthly Tracked Users (MTU) — a key input to your MoEngage bill. Merging duplicates into one profile reduces your MTU count, so cleaning up existing duplicates can also lower cost in addition to improving data accuracy.

Guide

Unified Identity (Identity Resolution)

Overview

Use Cases

Configure Multiple Identifiers

Step 1: Select Identifiers

Step 2: Review Merge Rules

Step 3: Activate Identity Resolution

Data Ingestion Support

Request Body

Sample cURL Request for Bulk Import API:

Pre-Flight Checklist for S2S User Creation

Cross-Profile Identifier Matching

Partial Identifier Payloads

Sample Codes

User Imports in Segment

Data Imports in Data

File Import & Segment CSV Processing Rules

Set Up Identifiers

Handle Existing Duplicate Users

Scenario 1: Email-id as the Identifier

Instance 1:

Instance 2:

Instance 3:

Scenario 2: Mobile number as the Identifier

Impact of Merging Users

System-Generated Merge Events

FAQs

​Overview

​Use Cases

​Configure Multiple Identifiers

​Step 1: Select Identifiers

​Step 2: Review Merge Rules

​Step 3: Activate Identity Resolution

​Data Ingestion Support

​Request Body

​Sample cURL Request for Bulk Import API:

​Pre-Flight Checklist for S2S User Creation

​Cross-Profile Identifier Matching

​Partial Identifier Payloads

​Sample Codes

​User Imports in Segment

​Data Imports in Data

​File Import & Segment CSV Processing Rules

​Set Up Identifiers

​Handle Existing Duplicate Users

​Scenario 1: Email-id as the Identifier

​Instance 1:

​Instance 2:

​Instance 3:

​Scenario 2: Mobile number as the Identifier

​Impact of Merging Users

​System-Generated Merge Events

​FAQs

Overview

Use Cases

Configure Multiple Identifiers

Step 1: Select Identifiers

Step 2: Review Merge Rules

Step 3: Activate Identity Resolution

Data Ingestion Support

Request Body

Sample cURL Request for Bulk Import API:

Pre-Flight Checklist for S2S User Creation

Cross-Profile Identifier Matching

Partial Identifier Payloads

Sample Codes

User Imports in Segment

Data Imports in Data

File Import & Segment CSV Processing Rules

Set Up Identifiers

Handle Existing Duplicate Users

Scenario 1: Email-id as the Identifier

Instance 1:

Instance 2:

Instance 3:

Scenario 2: Mobile number as the Identifier

Impact of Merging Users

System-Generated Merge Events

FAQs