openapi: 3.0.0
info:
  title: MoEngage - User Merge API
  description: "| <br><br>#### Note<br><br>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.<br><br> |\n\nThe 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.\n\nThere are two types of user merging in MoEngage:\n\n| Default merge | Manual Merge |\n| --- | --- |\n| <br><br>MoEngage merges users with the same ID<br><br> | <br><br>MoEngage merges users having different IDs<br><br> |\n| <br><br>Happens automatically, and no action is required from your side. For more information, refer to User Merge.<br><br> | <br><br>Does not happen automatically; the User Merge API needs to be called with the list of users to be merged along with their IDs.<br><br> |\n\n## API Endpoint\n\n```\nPOST https://api-0X.moengage.com/v1/customer/merge?app_id=\n```\n\nThe '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](https://help.moengage.com/hc/en-us/articles/360057030512-Data-Centers-in-MoEngage).\n\n## Authentication\n\nBasic authentication sends a Base64-encoded string containing username and password for all API requests.\n\nDo the following when you are using the API for the first-time authentication:\n\nFor 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:\n\n{\"Authorization\":\"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=\"}\n\n# Request Parameters\n\n| Key | Data Type | Sample Values | Description |\n| --- | --- | --- | --- |\n| <br><br>APP_ID<br><br> | <br><br>String<br><br> | <br><br>{\"APP_ID\": \"APP ID\"}<br><br> | <br><br>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.<br><br>Note: You can also fetch the APP ID from the following navigation: Settings -> App -> General Settings.<br><br> |\n\n# Request Headers\n\n| Key | Mandatory/Optional | Sample Values | Description |\n| --- | --- | --- | --- |\n| <br><br>Authorization<br><br> | <br><br>Mandatory<br><br> | <br><br>{\"Authorization\": \"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U==\"}<br><br> | <br><br>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.<br><br> |\n| <br><br>Content-Type<br><br> | <br><br>Mandatory<br><br> | <br><br>{\"Content-Type\": \"application/json\"}<br><br> | <br><br>Set the Content-Type header to application/json for using the User Merge API.<br><br> |\n\n# Request Body\n\n| Key | Mandatory/Optional | Values | Description |\n| --- | --- | --- | --- |\n| <br><br>merge_data<br><br> | <br><br>Mandatory<br><br> | <br><br>Array of Objects<br><br> | <br><br>This field contains the list of UID pairs of the users who are to be merged.\_<br><br>Example:<br><br>{<br><br>“merge_data”:<br><br>\_\_\_\_\_\\[\_ \_ // All the different pairs of users to merge<br><br>{<br><br>\_ “merged_user”: ““, // This user will merge into below user<br><br>\_ “retained_user”: “” \_ // Above user will merge into this user<br><br>},<br><br>{<br><br>\_ “merged_user”: ““, // This user will merge into below user<br><br>\_ “retained_user”: “” \_ // Above user will merge into this user<br><br>}<br><br>\\]<br><br>}<br><br>  <br><br>Every object in the Array contains a pair of UID strings - the ‘merged_user’ and the ‘retained_user’.\_<br><br>Note:\_<br><br>1. UID is the unique identifier for a user maintained by you. MoEngage stores this identifier in the\_[ID attribute in the user profile](https://help.moengage.com/hc/en-us/articles/360044285511-User-Profile#h_01FTESCBSZJY53DJ2NS18YVE0E).<br>2. If the merging of any user fails in the array, it will skip that object and continue with others.<br><br> |\n\n# Response\n\n| Key | Data Type | Description |\n| --- | --- | --- |\n| <br><br>status<br><br> | <br><br>String<br><br> | <br><br>This field contains a brief description (“success” and “fail”) of the request status.<br><br> |\n| <br><br>operation<br><br> | <br><br>String<br><br> | <br><br>This field contains “created” when there is no error in the payload, and the user merge is successful.<br><br> |\n| <br><br>error<br><br> | <br><br>JSON Object<br><br> | <br><br>This field contains the details of the error:<br><br>1. message - the error message indicating the reason for the failure of the request<br>2. type - the error type indicating the failure type\_<br>3. request_id - the unique identifier associated with every request<br><br> |\n\n# Response Codes\n\n| Status Code | Request State | Description |\n| --- | --- | --- |\n| <br><br>200<br><br> | <br><br>Success<br><br> | <br><br>This response is returned when the request is processed successfully.\_<br><br> |\n| <br><br>400<br><br> | <br><br>Bad Request<br><br> | <br><br>This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.<br><br> |\n| <br><br>401<br><br> | <br><br>Authorization Failure<br><br> | <br><br>This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header.<br><br> |\n| <br><br>403<br><br> | <br><br>Account Suspended Temporarily<br><br> | <br><br>This response is returned when the user account that is being merged has been suspended temporarily.<br><br> |\n| <br><br>409<br><br> | <br><br>API SECRET not configured<br><br> | <br><br>This response is returned when the authorization fails due to the APP SECRET key not being set on the Dashboard.<br><br> |\n| <br><br>413<br><br> | <br><br>Payload Limit Exceeded<br><br> | <br><br>This response is returned when the payload size has exceeded the limit set.<br><br> |\n| <br><br>415<br><br> | <br><br>Unsupported media type<br><br> | <br><br>This response is returned when the header “Content-Type” is not provided/is not supported.<br><br> |\n| <br><br>429<br><br> | <br><br>Rate Limit Breach<br><br> | <br><br>This response is returned when the number of requests per minute has exceeded the rate limit.<br><br> |\n| <br><br>5xx<br><br> | <br><br>Internal Server Error<br><br> | <br><br>This response is returned when the system runs into an unexpected error.<br><br> |\n\n# Rate Limit\n\nThe rate limit is 1000 user updates per minute."
  version: 1.0.0
servers:
  - url: https://api-{{0x}}.moengage.com
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
paths:
  /v1/customer/merge:
    post:
      tags:
        - General
      summary: User Merge API
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                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
      security:
        - basicAuth: []
      parameters:
        - name: app_id
          in: query
          schema:
            type: string
          example: '{{APP_ID}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
