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 whose values 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 feature, please refer to our help document.

Purpose

To merge upto three duplicate records into a single record and delete the duplicates.

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

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

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

Input JSON

master_record_fieldsJSON array, optional
Specify the API name of the file upload and image upload fields to retain them in the merged record.
- api_namestring, mandatory
  Represents the API name of the file upload or image upload fields.
- _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. Use GET Records API to retrieve the unique IDs of the files or attachments.
  - idstring, mandatory
    The unique ID of the attachment.
dataJSON array, mandatory
An array of objects specifying the child records and the fields whose values you want to use in the merged record.
idstring, mandatory
Represents the unique ID of the child record.
- _fieldsJSON array, mandatory
  Specify the API names of the fields from the child record whose values you wish to merge into the master record.
  - api_namestring, mandatory
    Represents the API name of the fields in the child record that you want to include in the merge.

Notes

If an image upload or file upload is not specified, all 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. This meas that it performs an asynchronous action, and the response to your request will not be available immediately. Instead, you will receive a unique job_id in the response. You can use this job_id to retrieve the status of your merge action. For details, please refer to the Get Records Merge Status API.
The merge JSON array can only contain one object, while the data JSON array can have a maximum of two child records. Exceeding these limits will result in errors.
Each field should only be mentioned once across the master_record_fields and data arrays.
Only open deals can be merged; closed deals will trigger an error.
The closing date, stage, probability, and expected revenue fields will be automatically populated based on the master record and should not be specified in the request.
Records currently locked or in an approval/review process cannot be merged.

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
  Resolution: Specify a valid record ID.
- The merge JSON array has reached its limit
  Resolution: The merge JSON array can have only one JSON object.
- The data JSON object has reached its limit
  Resolution: The data JSON array can have a maximum of two values, corresponding to the two child records.
- Atleast one child record ID is required to be merged
  Resolution: The data JSON array cannot be empty. Please specify valid data.
- Reporting_To and Account_Name should belong to the same record
  Resolution: The Reporting_To and Account_Name should be used from the same record.
MANDATORY_NOT_FOUNDHTTP 400
- The API names in the field JSON array cannot be empty
  Resolution: Specify the valid API names in the merge JSON array.
- The API names in the merge JSON array cannot be empty
  Resolution: Specify the valid API names in the fields JSON array.
- The ID of the child record is empty
  Resolution: Specify valid IDs for the child record.
INVALID_MODULEHTTP 400
The module name given seems to be invalid
Resolution: Please specify the a module name in the URL. Refer to the request URL section at the beginning of this page.
NOT_ALLOWEDHTTP 400
- This record ID is not allowed to be merged
  Resolution: The record you are trying to merge has already been scheduled for merging. Please specify another valid record ID.
- Record is not allowed for merging
  Resolution: The record is currently locked or in Approval / Review Process. Please unlock the record and merge, or contact the admin.
- Closing date will be automatically populated based on master record
  Resolution: Do not specify the closing date field. The closing date will be fetched automatically from the master record.
- Stage field will be automatically populated based on chosen Pipeline
  Resolution: 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.
- Only Open Deals can be merged
  Resolution: Do not use the closed deals. The merge action will take place only with the open deals.
- Probability and Expected Revenue fields will be automatically populated based on chosen Stage
  Resolution: Do not 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
  Resolution: You have specified the same record ID for master and/or child records. Please specify different record IDs for merging.
- Field has already been mentioned for other record in merge
  Resolution: You have already specified this field. Please specify each field only once, either in the master_record_fields array, or one of the data arrays.
DEPENDENT_FIELD_MISSINGHTTP 400
- The _data array is not specified for the master record
  Resolution: 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.
- The _data array is not mentioned for the child record
  Resolution: 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 request method is incorrect.
Resolution: Use the HTTP POST method to make this API call. Any other request method will result in this error.
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
The access token you have used to make this API call does not have the required scope.
Resolution: Generate a new access token with the required scopes for this API. Refer to the Scope section at the beginning of this page for the list of required scopes.
AUTHENTICATION_FAILUREHTTP 401
You have not authorized the API call with valid access token.
Resolution: Include a valid access token in the request header to authorize the API call.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the request URL section at the beginning of this page for more details.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.

Sample Response

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

Sample Response for scheduled merge call

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