Merge Records API

This API merges up to three duplicate records into a single one, deleting the duplicates. You can specify one as the master record which is to be retained post-merge, and the other two as child records which are to be deleted. You can specify fields from the child records that are to be used for the merged record, and retain the master record values for the remaining fields. 
To explore more on the Find and Merge, please refer to this link.

Purpose

To merge upto three duplicate records into a single record.

Endpoints

POST /{module_api_name}/{master_record_id}/actions/merge

Request Details

Request URL

{api-domain}/crm/{version}/{module_api_name}/{master_record_id}/actions/merge

Supported Modules

Leads, Contacts, Accounts, Potentials, Vendors and Custom.

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope = ZohoCRM.modules.{module_name}.{operation_type}

Possible Module Names

leads, contacts, potentials, accounts, vendors, and custom.

Possible Operation Types

WRITE - Edit records in a module.
ALL - Full access to the record.

Sample Request

Curl Deluge

Copiedcurl "https://www.zohoapis.com/crm/v7/Leads/2423488000000500064/actions/merge"
-X POST
-d @input.json
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Copiedresponse = invokeurl
[
	url: "https://www.zohoapis.com/crm/v7/Leads/2423488000000500064/actions/merge"
	type: GET
	connection:"crm_oauth_connection"
];
info response;

Input JSON Keys

master_record_fieldsJSON array, optional
Specify the API names of the fields from which values should be retained in the master record during a merge action. For example, if a record in the Leads module has five fields, use this JSON array to select one field among the five fields.
- api_namestring, mandatory
  It represents the API name of the field in the master record.
- _dataJSON array, optional
  It represents the unique ID of a file or attachment. This field is specifically used for File Upload and Image Upload fields in a record. Refer to the GET Records API to retrieve the unique IDs of the files or attachments.
  - idstring, mandatory
    It represent the unique ID of an attachment.
dataJSON array, mandatory
Specify the details of the child records here.
idstring, mandatory
It represents the ID of the child record.
- _fieldsJSON array, mandatory
  It represents the API names of the fields in the child record where you want their values to merge into the master record. After a successful merge, the child record will be deleted.
  - api_namestring, mandatory
    It represents the API name of the fields in the child record.

Notes

The _fields JSON array does not have any number of objects restrictions
You can specify only a single data JSON array which can contain upto two objects.
You can specify only a single merge JSON array.
If an image upload or file upload is not specified, the images/files in the master record will be retained.
If '_data': null is provided, all the images/files for that specific field will be deleted.
If a child record has more than 1000 records in any of its related lists, then the merge action will be scheduled, meaning that it performs an asynchronous action, and the response to your request will not be available immediately.

Sample Input

Copied{
    "merge": [
        {
            "master_record_fields": [
                {
                    "api_name": "Company"
                },
                {
                    "api_name": "File_Upload",
                    "_data": [
                        {
                            "id": "2423488000000538058"
                        }
                    ]
                }
            ],
            "data": [
                {
                    "id": "2423488000000495876",
                    "_fields": [
                        {
                            "api_name": "Annual_Revenue"
                        },
                        {
                            "api_name": "Last_Name"
                        }
                    ]
                }
            ]
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- Master record id is not available
- The size of the merge JSON array is more than 1
- The size of the data JSON object is more than 2
- Atleast one child record id is required to be merged
- Reporting_To and Account_Name should belong to the same record
Resolutions:
- Specify a valid ID of the master record.
- The merge JSON array can have only one value, which corresponds to the master record.
- The data JSON array can have a maximum of two values, corresponding to two child records.
- The data JSON array cannot be empty. Please specify valid data.
- Specify both the Reporting_To and Account_Name in the same JSON array.
MANDATORY_NOT_FOUNDHTTP 400
- The API names in the field JSON array cannot be empty
- The API names in the merge JSON array cannot be empty
- The ID of the child record is empty
Resolutions:
- Specify the valid API names in the merge JSON array.
- Specify the valid API names in the fields JSON array.
- Specify the ID of the child record.
INVALID_MODULEHTTP 400
The module name given seems to be invalid
Resolution: Please specify the valid module name in the URL. Refer to the request URL section above.
NOT_ALLOWEDHTTP 400
- This record id is not allowed to be merged
- Closing date will be automatically populated based on master record
- Stage field will be automatically populated based on chosen Pipeline
- Only Open Deals can be merged
- Probability and Expected Revenue fields will be automatically populated based on chosen Stage
Resolutions:
- The record you are trying to merge has already been scheduled for merging. Please specify a valid record ID.
- Do not specify the closing date field. The closing date will be fetched automatically from the master record.
- Do not specify the stage field. The stage value will be automatically fetched from the chosen pipeline. If you specify the pipeline of the child record, then the stage value will be fetched from the respective pipeline.
- Do not use the closed deals. The merge action will take place only with the open deals.
- You cannot specify the Expected Revenue and Probability fields. The values of these fields will be automatically fetched based on the stage.
DUPLICATE_DATAHTTP 400
- Similar ID is already given for merging
- Field has already been mentioned for other record in merge
Resolutions:
- The given IDs are same. Please specify the valid record IDs.
- Same field is used more than once. Please specify unique field API names.
DEPENDENT_FIELD_MISSINGHTTP 400
- The _data array is not specified for the master record
- The _data array is not mentioned for the child record
Resolutions:
- Specify the unique ID of a file or image from the _data JSON array. The dependent "id" field is missing for the File_Upload or Image_Upload field in the master record.
- Specify the unique ID of a file or image in the _data JSON array. The dependent "id" field is missing for the File_Upload or Image_Upload field in the child record.
LIMIT_EXCEEDEDHTTP 400
The total number of given files cannot be more than the maximum limit.
Resolution: Please check the maximum limits in the response, for example, if "maximum_length": 1, it means the maximum allowed length for attaching an image or file is 1.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL.
Specify a valid request method. Refer to the endpoints section above.
INVALID_MODULEHTTP 400
The module name given seems to be invalid
Resolution: You have specified an invalid module name.
Specify a valid module name.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have ZohoCRM.modules.{module_name}.WRITE scope.
Create a new client with valid scope. Refer to scope section above.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the request URL section above.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "merge": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "2423488000000500064"
            },
            "message": "The records have been merged successfully",
            "status": "success"
        }
    ]
}

The sample response above is for a successful merge.

Sample Response for scheduled merge call

Copied{
    "merge": [
        {
            "code": "SCHEDULED",
            "details": {
                "job_id": "2423488000000513988"
            },
            "message": "The records have been scheduled for merge",
            "status": "success"
        }
    ]
}