Skip to main content
POST
/
customer
/
merge
Merge Users
curl --request POST \
  --url https://api-0{dc}.moengage.com/v1/customer/merge \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merge_data": [
    {
      "merged_user": "<string>",
      "retained_user": "<string>"
    }
  ]
}
'
{
  "status": "success",
  "operation": "created"
}

​
Rate limit

The rate limit is 1000 user updates per minute.

​
Types of user merging in MoEngage

  • Default or normal merge:
    • MoEngage merges users with the same ID.
    • Happens automatically, and no action is required from your side.
  • Manual merge:
    • MoEngage merges users having different IDs.
    • Does not happen automatically; you must call the Merge User API with the list of users to be merged along with their IDs.
  • User Merging is a complex functionality and, if misused, can lead to data integrity issues. If the data passed to the API is incorrect, resulting in a merge of two unintended users, MoEngage will not be able to recover/rectify the data. The retained user would have erroneous data, and segmentation queries would not provide the right results.
  • MoEngage does not support transitive/canonical merging. For example, if user A is merged to B (A ->B) and then user B is merged to C (B ->C), in this scenario, events of user A are not moved to user C.
  • The Merge User API is not functional in workspaces where the Identity Resolution feature is enabled.
  • If you are updating the Unique Identifier for a user, use the Merge User API at least 2 hours after you have updated the Unique Identifier.
  • Ensure that the data passed to the API is accurate. We recommend you test the merging starting with a small batch of users, such as 1, 5, 10, 20, 50, etc. Verify the merged data and users before proceeding with a bulk update.

​
Terms to Know

  • Retained User: This is the user that is retained in the system. The merged user’s attributes and associated devices are mapped to the retained user post-merge. Reachability calculation is done for the retained user based on the devices. All of the user attributes of the merged user are moved to the retained user. If an attribute is present for the retained user and the same attribute is not for the merged user, the attribute is retained for the retained user.
  • Merged user: All the data of this user will merge into the retained user. Merged users will be deleted after 30 days of inactivity. If MoEngage receives any event or user property for the merged user after the merging activity, the merged user will not be deleted. The following happens in MoEngage post-user merging:
    • In the user profile, all events of the last 30 days are moved from the merged user to the retained user.
    • Segmentation and campaign have moved all of the data from merged user to retained user.

Authorizations

​
Authorization
string
header
required

Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.

  • Username: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).
  • Password: Use your API Key, which you can find within the Data tile.

Note: After you generate and save the Data API Key, DO NOT generate a new key unless there is a security breach. After you generate a different Data API key and save it, the authentication will start failing. You must update your existing data tracking.

For more information on authentication and getting your credentials, refer here.

Query Parameters

​
app_id
string
required

This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).

Body

application/json
​
merge_data
object[]

This field contains the list of UID pairs of the users who are to be merged.

Example:

{
  "merge_data": [    // All the different pairs of users to merge
    {
      "merged_user": "<sample_uid>", // This user will merge into below user
      "retained_user": "<sample_uid>"   // Above user will merge into this user
    },
    {
      "merged_user": "<sample_uid>", // This user will merge into below user
      "retained_user": "<sample_uid>"   // Above user will merge into this user
    }
  ]
}
  • Every object in the Array contains a pair of UID strings - the ‘merged_user’ and the ‘retained_user’.
  • UID is the unique identifier for a user maintained by you. MoEngage stores this identifier in the ID attribute in the user profile.
  • If the merging of any user fails in the array, it will skip that object and continue with others.

Response

This response is returned when the request is processed successfully.

​
status
string

This field contains the status of the request and specifies whether the request was successful. Supported values are : "success", "failure"

Example:

"success"

​
operation
string

This field contains “created” when there is no error in the payload, and the user merge is successful.

Example:

"created"