User Merge
 

Note

This API is a closed feature and is not available by default. To enable this API for your account, please connect with your CSM or drop a mail to support@moengage.com.

Overview

The User Merge API merges two users in MoEngage based on their ID. ID is a client-defined identifier for a user. This API can be used when multiple profiles have been created for a single user. For example, a user registered once with a mobile number and once with an email id can be merged. Duplicate users created due to integration or tech issues can also be merged.

There are two types of user merging in MoEngage:

      • Default or normal merge
      • Manual merge
Default merge Manual Merge

MoEngage merges users with the same ID

MoEngage merges users having different IDs

Happens automatically, and no action is required from your side. For more information, refer to User Merge.

Does not happen automatically; the User Merge API needs to be called with the list of users to be merged along with their IDs.

 

Warning

User Merging is a complex functionality and, if used incorrectly, 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. 

Please 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, the last 100 events received in the last 1 hour 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.

API Endpoint

POST https://api-0X.moengage.com/v1/customer/merge?app_id=<app_id>

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

Authentication

Basic authentication sends a Base64-encoded string containing username and password for all API requests.

Do the following when you are using the API for the first-time authentication:

      1. Navigate to Settings > APIs > DATA API Settings.
      2. Click Generate Key
      3. Save the details on the Data APIs settings page. User name - DATA API ID Password - DATA API KEY

For example, basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. The string is passed in the authorization header as follows:

{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

Request Parameters

Key Data Type Sample Values Description

app_id

String

{"app_id": "APP ID"}

This is the APP ID of your MoEngage account, and needs to be passed along with the request. You can find your MoEngage APP ID in the MoEngage Dashboard API Settings. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication.

Note: You can also fetch the APP ID from the following navigation: Settings -> App -> General Settings.

 

Request Headers

Key Mandatory/Optional Sample Values Description

Authorization

Mandatory

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This is the authentication parameter for access control and needs to be passed along with the request. The APP KEY and API SECRET need to be picked up from the DATA API Settings in MoEngage Dashboard, and a Basic Authorization header needs to be created and set in the header. Navigation: Settings -> API -> General Settings -> DATA API section. For more information, refer to Authentication.

Content-Type

Mandatory

{"Content-Type": "application/json"}

Set the Content-Type header to application/json for using the User Merge API.

 

Request Body

Key Mandatory/Optional Values Description

merge_data

Mandatory

Array of Objects

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’. 

Note: 

  1. UID is the unique identifier for a user maintained by you. MoEngage stores this identifier in the ID attribute in the user profile.
  2. If the merging of any user fails in the array, it will skip that object and continue with others.

 

Response

Key Data Type Description

status

String

This field contains a brief description (“success” and “fail”) of the request status.

operation

String

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

error

JSON Object

This field contains the details of the error:

  1. message - the error message indicating the reason for the failure of the request
  2. type - the error type indicating the failure type 
  3. request_id - the unique identifier associated with every request

 

Response Codes

Status Code Request State Description

200

Success

This response is returned when the request is processed successfully. 

400

Bad Request

This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.

401

Authorization Failure

This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header.

403

Account Suspended Temporarily

This response is returned when the user account that is being merged has been suspended temporarily.

409

API SECRET not configured

This response is returned when the authorization fails due to the APP SECRET key not being set on the Dashboard.

413

Payload Limit Exceeded

This response is returned when the payload size has exceeded the limit set.

415

Unsupported media type

This response is returned when the header “Content-Type” is not provided/is not supported.

429

Rate Limit Breach

This response is returned when the number of requests per minute has exceeded the rate limit.

5xx

Internal Server Error

This response is returned when the system runs into an unexpected error.

Rate Limit

The rate limit is 1000 user updates per minute.

Sample cURL Request


curl --location -g --request POST 'https://api-{{0X}}.moengage.com/v1/customer/merge?app_id={{APP_ID}}' \
--header 'Authorization: Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "merge_data": [
        {
            "merged_user": "user_id_that_you_want_to_merge",
            "retained_user": "user_id_that_you_want_to_retain"
        },
        {
            "merged_user": "user_id_that_you_want_to_merge",
            "retained_user": "user_id_that_you_want_to_retain"
        }
    ]
}'

Sample Response

200 400 401 403 409 413 415 429500

Sample Response for a successful request
{
   "status":"success",
   "operation":"created"

}

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

  1. Will the merged user information be available after using this API?

    No, the merged user will get deleted after calling this API. All the user attributes and devices of the merged user will be transferred to the retained user.

  2. What will happen to the reachability of the retained user?

    The reachability status of the user will be recalculated based on the devices present after merging the user.

  3. Can any two users be merged?

    Any registered user present in the MoEngage system can be merged with another registered user irrespective of the source of creation.

  4. Should both users have a device attached to them before merging?

    Not necessarily; we allow the merging of users with or without devices.

  5. Is there any restriction on the number of times a user can be merged?

    No.

  6. Is there any restriction on the number of devices a merged/retained should have?

    No.

  7. What happens to the merged_user after the merge?

    This user will get deleted, and if any devices are attached to this user, they will be associated with the retained_ user, and all the events and user details of merged_user will reflect on the retained_user.  A merge event MOE_USER_MERGE_EVENT will be added to the merged_user (who will only have the MoEngage ID now).

  8. What happens to retained_user after the merge?

    The retained_user will now have all the user, device, and event details of merged_user along with details of retained_user, and a merge eventMOE_USER_MERGED will be added to retained_user.

  9. What happens if a user creation request comes with the same ID as the deleted user (which is deleted after the merge)?

    We will create a new user with that ID, but the MoEngage ID of this user will be different as compared to the deleted user.

  10. What happens to the reachability if both users do not have devices?

    The user will not be reachable.

  11. What is the SLA to see user details reflect after the merge?

    The maximum SLA is 30 minutes.

  12. How are events copied from the merged user to the retained user?

    In the user profile, the last 100 events received in the last 1 hour are moved from the merged user to the retained user.

Was this article helpful?
0 out of 0 found this helpful