Zoho: Merge Records

← Find and merge operations · Get started

Operation zoho.mergerecords

Provider route: POST /crm/v8/{module}/{masterRecordId}/actions/merge. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/zoho with npm, or alter-sdk-zoho with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { ZohoIntegration } from "@alter-ai/zoho";

async function execute(input: Parameters<ZohoIntegration["findAndMerge"]["mergeRecords"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new ZohoIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.findAndMerge.mergeRecords(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_zoho import ZohoIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = ZohoIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.find_and_merge.merge_records(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.masterRecordId	string	Required within parent	Master record identifier (int64 as string) Maximum length: 50 Pattern: ^[0-9]+$
path.module	string	Required within parent	Valid CRM module name One of: Accounts, Contacts, Leads, Deals, Cases, Campaigns
query	object	Optional	Additional keys: not allowed
query.feature	string	Optional	One of: web_record_approval
body	object	Required within parent	Specify the merge configuration for the records to be consolidated. Additional keys: not allowed
body.merge	array	Required within parent	Specify the configurations for the merge. The array must contain exactly one object. Maximum items: 1
body.merge[]	object	Each item	Each object specifies the configuration for a single merge operation, including the child records to be merged and the field value selections for the merged record. Additional keys: not allowed
body.merge[].data	array	Required within parent	Specify the child records to be merged into the master record. The array must contain a minimum of one and a maximum of two child record objects. Maximum items: 2 Minimum items: 1
body.merge[].data[]	object	Each item	Each object specifies the child record identifier and the fields whose values should be used in the merged record. Additional keys: not allowed
body.merge[].data[]._fields	array	Optional	Specify the API names of the fields from the child record whose values you wish to merge into the master record. Maximum items: 100
body.merge[].data[]._fields[]	object	Each item	Each object specifies the API name of the field and, for file upload or image upload fields, the attachment IDs to retain. Additional keys: not allowed
body.merge[].data[]._fields[]._data	JSON	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](record.yaml#$.paths./{module}.get) to retrieve the unique IDs of the files or attachments.
body.merge[].data[]._fields[]._data (anyOf 1)	array	Alternative	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](record.yaml#$.paths./{module}.get) to retrieve the unique IDs of the files or attachments. Maximum items: 50
body.merge[].data[]._fields[]._data (anyOf 1)[]	object	Each item	Each object specifies the unique identifier of the file or image attachment. Additional keys: not allowed
body.merge[].data[]._fields[]._data (anyOf 1)[].id	string	Required within parent	Specify the unique numeric identifier of the file or image attachment. Maximum length: 50 Pattern: ^[0-9]+$
body.merge[].data[]._fields[]._data (anyOf 2)	null	Alternative	Set to null to delete all file or image attachments for this field in the merged record.
body.merge[].data[]._fields[].api_name	string	Required within parent	Represents the API name of the fields in the child record that you want to include in the merge. Maximum length: 100
body.merge[].data[].id	string	Required within parent	Specify the unique identifier of the child record to be merged. Maximum length: 50 Pattern: ^[0-9]+$
body.merge[].master_record_fields	array	Optional	Specify the fields from the master record whose values should be retained in the merged record. Use this for file upload or image upload fields in the master record. Maximum items: 100
body.merge[].master_record_fields[]	object	Each item	Each object specifies the API name of a master record field like file upload or image upload fields, the attachment IDs to retain. Additional keys: not allowed
body.merge[].master_record_fields[]._data	JSON	Optional	Specify the file or image attachment IDs to retain for this master record field, or set to null to delete all attachments for this field in the merged record. > 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](find_and_merge.yaml#$.paths./{module}/{masterRecordId}/actions/merge.get). > - 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.
body.merge[].master_record_fields[]._data (anyOf 1)	array	Alternative	Specify the file or image attachment IDs to retain for this master record field, or set to null to delete all attachments for this field in the merged record. > 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](find_and_merge.yaml#$.paths./{module}/{masterRecordId}/actions/merge.get). > - 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. Specify the file or image attachment IDs to retain for this master record field, or set to null to delete all attachments for this field in the merged record. > 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](find_and_merge.yaml#$.paths./{module}/{masterRecordId}/actions/merge.get). > - 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. Maximum items: 50
body.merge[].master_record_fields[]._data (anyOf 1)[]	object	Each item	Specify the unique identifier of the file or image attachment to retain in the master record. Additional keys: not allowed
body.merge[].master_record_fields[]._data (anyOf 1)[].id	string	Required within parent	Specify the unique identifier of the file or image attachment to retain. Maximum length: 50 Pattern: ^[0-9]+$
body.merge[].master_record_fields[]._data (anyOf 2)	null	Alternative	Set to null to delete all file or image attachments for this master record field in the merged record.
body.merge[].master_record_fields[].api_name	string	Required within parent	Specify the API name of the master record field to retain in the merged record. Maximum length: 100

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	JSON	Root	Response when the merge operation was initiated - either completed synchronously or scheduled asynchronously.
$ (anyOf 1)	object	Alternative	Response when the merge operation is completed or scheduled for processing. Additional keys: not allowed
$ (anyOf 1).merge	array	Required within parent	Contains the list of merge operation results indicating whether the merge completed or was scheduled. Maximum items: 1
$ (anyOf 1).merge[]	JSON	Each item	Each object represents a merge result item indicating whether the operation completed synchronously or was scheduled for processing.
$ (anyOf 1).merge[] (anyOf 1)	object	Alternative	Successful merge completion response, returned when the merge was processed synchronously. Additional keys: not allowed
$ (anyOf 1).merge[] (anyOf 1).code	string	Required within parent	Represents the success code for a completed merge. Possible values: SUCCESS - The records were merged successfully. Known values: SUCCESS
$ (anyOf 1).merge[] (anyOf 1).details	object	Required within parent	Contains the details of the completed merge, including the ID of the master record retained after the merge. Additional keys: not allowed
$ (anyOf 1).merge[] (anyOf 1).details.id	string	Required within parent	Represents the unique identifier of the master record retained after the merge. Maximum length: 50 Pattern: ^[0-9]+$
$ (anyOf 1).merge[] (anyOf 1).message	string	Required within parent	Represents the success message for the completed merge operation. Maximum length: 500
$ (anyOf 1).merge[] (anyOf 1).status	string	Required within parent	Represents the status of the merge operation. Possible values: success - The merge completed successfully. Known values: success
$ (anyOf 1).merge[] (anyOf 2)	object	Alternative	Scheduled merge operation response, returned when the merge was queued for asynchronous processing. Additional keys: not allowed
$ (anyOf 1).merge[] (anyOf 2).code	string	Required within parent	Represents the code indicating that the merge was scheduled for background processing. Possible values: SCHEDULED - The merge operation was queued for asynchronous processing. Known values: SCHEDULED
$ (anyOf 1).merge[] (anyOf 2).details	object	Required within parent	Contains the details of the scheduled merge, including the job ID for tracking the merge status. Additional keys: not allowed
$ (anyOf 1).merge[] (anyOf 2).details.job_id	string	Required within parent	Represents the unique identifier of the scheduled merge job. Use this ID with the [Get Merge Job Status API](find_and_merge.yaml#$.paths./{module}/{masterRecordId}/actions/merge.get) to check the status of the merge. Maximum length: 50 Pattern: ^[0-9]+$
$ (anyOf 1).merge[] (anyOf 2).message	string	Required within parent	Represents the message about the scheduled merge operation. Maximum length: 500
$ (anyOf 1).merge[] (anyOf 2).status	string	Required within parent	Represents the status of the scheduling operation. Possible values: success - The merge was successfully scheduled. Known values: success

Policy, approvals and errors

SDK function policy ID: zoho.mergerecords. Catalog operation: mergeRecords. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source