API endpoints for finding and merging duplicate records in Zoho CRM modules. Supports querying merge job status and performing record merge operations with field mapping and validation.
{
"openapi": "3.1.0",
"info": {
"title": "Find And Merge",
"description": "API endpoints for finding and merging duplicate records in Zoho CRM modules. Supports querying merge job status and performing record merge operations with field mapping and validation.",
"version": "8.0"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"enum": [
"com",
"eu",
"in",
"cn",
"au"
],
"default": "com",
"description": "API Server URL TLD"
},
"version": {
"default": "v8",
"description": "API Version"
}
}
}
],
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.modules.read",
"ZohoCRM.settings.modules.all",
"ZohoCRM.settings.all",
"ZohoCRM.modules.CREATE"
]
}
],
"paths": {
"/{module}/{masterRecordId}/actions/merge": {
"get": {
"summary": "Get Merge Job Status",
"description": "Retrieves the status of merge jobs for finding and tracking record merge operations in Zoho CRM modules.",
"operationId": "getMergeJobStatus",
"parameters": [
{
"$ref": "#/components/parameters/JobId"
},
{
"$ref": "#/components/parameters/MasterRecordId"
},
{
"$ref": "#/components/parameters/Module"
}
],
"responses": {
"200": {
"description": "Successfully retrieved merge job status information",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response containing merge job status information",
"additionalProperties": false,
"properties": {
"merge": {
"type": "array",
"description": "Array of merge job status records",
"maxItems": 100,
"items": {
"type": "object",
"description": "Individual merge job status",
"additionalProperties": false,
"properties": {
"job_id": {
"type": "string",
"description": "Unique identifier of the merge job",
"pattern": "^[0-9]+$",
"maxLength": 50
},
"status": {
"type": "string",
"description": "Current status of the merge job",
"enum": [
"SCHEDULED",
"running",
"completed",
"failed"
]
}
},
"required": [
"job_id",
"status"
]
}
}
},
"required": [
"merge"
]
}
}
}
},
"204": {
"description": "No merge jobs found for the specified criteria"
},
"400": {
"description": "Bad request due to validation errors, invalid data, or business rule violations",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"description": "Standard error response for invalid data or record issues",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code indicating the type of failure",
"enum": [
"INVALID_DATA",
"INVALID_MODULE",
"NOT_ALLOWED"
]
},
"details": {
"type": "object",
"description": "Additional error details with context information",
"additionalProperties": false,
"properties": {
"resource_path_index": {
"type": "integer",
"format": "int32",
"description": "Index of the resource path parameter that caused the error"
},
"api_name": {
"type": "string",
"description": "API name of the field or resource that caused the error",
"maxLength": 100
},
"json_path": {
"type": "string",
"description": "JSON path to the field that caused the error",
"maxLength": 200
},
"maximum_length": {
"type": "integer",
"format": "int32",
"description": "Maximum allowed length for the field"
},
"minimum_length": {
"type": "integer",
"format": "int32",
"description": "Minimum required length for the field"
}
}
},
"message": {
"type": "string",
"description": "Human-readable error message describing the issue",
"maxLength": 500
},
"status": {
"type": "string",
"description": "Status of the request",
"enum": [
"error"
]
}
},
"required": [
"code",
"message",
"status"
]
},
{
"type": "object",
"description": "Error response with merge array structure",
"additionalProperties": false,
"properties": {
"merge": {
"type": "array",
"description": "Array of error responses for merge operations",
"maxItems": 10,
"items": {
"type": "object",
"description": "Individual merge operation error",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Error code for the specific merge operation",
"enum": [
"MANDATORY_NOT_FOUND",
"NOT_ALLOWED",
"INVALID_DATA",
"DUPLICATE_DATA",
"DEPENDENT_FIELD_MISSING",
"LIMIT_EXCEEDED"
]
},
"details": {
"type": "object",
"description": "Detailed error information for merge operation",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the field that caused the error",
"maxLength": 100
},
"json_path": {
"type": "string",
"description": "JSON path to the problematic field",
"maxLength": 200
},
"resource_path_index": {
"type": "integer",
"format": "int32",
"description": "Index of the resource path parameter"
},
"maximum_length": {
"type": "integer",
"format": "int32",
"description": "Maximum allowed length"
},
"minimum_length": {
"type": "integer",
"format": "int32",
"description": "Minimum required length"
},
"MAXIMUM_SIZE": {
"type": "string",
"description": "Maximum size limit for files",
"maxLength": 50
},
"limit_due_to": {
"type": "array",
"description": "Fields that caused the limit to be exceeded",
"maxItems": 20,
"items": {
"type": "object",
"description": "Field information for limit exceeded error",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the field",
"maxLength": 100
},
"json_path": {
"type": "string",
"description": "JSON path to the field",
"maxLength": 200
}
},
"required": [
"api_name",
"json_path"
]
}
},
"data": {
"type": "array",
"description": "Data records with association information",
"maxItems": 10,
"items": {
"type": "object",
"description": "Record with association details",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Record identifier",
"pattern": "^[0-9]+$",
"maxLength": 50
},
"_associated_places": {
"type": "array",
"description": "Associated places information",
"maxItems": 50,
"items": {
"type": "object",
"description": "Association information",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"description": "Type of association",
"maxLength": 100
},
"resources": {
"type": "array",
"description": "Associated resources",
"maxItems": 50,
"items": {
"type": "object",
"description": "Resource information",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Resource identifier",
"pattern": "^[0-9]+$",
"maxLength": 50
},
"name": {
"type": "string",
"description": "Resource name",
"maxLength": 200
}
},
"required": [
"id",
"name"
]
}
}
},
"required": [
"type",
"resources"
]
}
}
},
"required": [
"id"
]
}
},
"dependee": {
"type": "object",
"description": "Dependent field information",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the dependent field",
"maxLength": 100
},
"json_path": {
"type": "string",
"description": "JSON path to the dependent field",
"maxLength": 200
}
},
"required": [
"api_name",
"json_path"
]
}
}
},
"message": {
"type": "string",
"description": "Error message for the merge operation",
"maxLength": 500
},
"status": {
"type": "string",
"description": "Status of the merge operation",
"enum": [
"error"
]
}
},
"required": [
"code",
"message",
"status"
]
}
}
},
"required": [
"merge"
]
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.modules.read"
]
}
]
},
"post": {
"summary": "Merge Records",
"description": "Merges duplicate records in Zoho CRM modules with field mapping and validation. Supports synchronous and asynchronous merge operations.",
"operationId": "mergeRecords",
"parameters": [
{
"$ref": "#/components/parameters/MasterRecordId"
},
{
"$ref": "#/components/parameters/Module"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Request body for merging records with field mapping and validation",
"additionalProperties": false,
"properties": {
"merge": {
"type": "array",
"description": "Array of merge operations to be performed",
"maxItems": 1,
"items": {
"type": "object",
"description": "Individual merge operation configuration",
"additionalProperties": false,
"properties": {
"data": {
"type": "array",
"description": "Array of child records to be merged (minimum 1, maximum 2)",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "object",
"description": "Child record configuration for merge",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the child record to be merged",
"pattern": "^[0-9]+$",
"maxLength": 50
},
"_fields": {
"type": "array",
"description": "Array of field configurations for the child record",
"maxItems": 100,
"items": {
"type": "object",
"description": "Field configuration for merge operation",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the field to be configured",
"maxLength": 100
},
"_data": {
"oneOf": [
{
"type": "array",
"description": "Array of file/image upload data",
"maxItems": 50,
"items": {
"type": "object",
"description": "File or image upload information",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the file or image",
"pattern": "^[0-9]+$",
"maxLength": 50
}
},
"required": [
"id"
]
}
},
{
"type": "null",
"description": "No file data (will delete all files for this field)"
}
]
}
},
"required": [
"api_name"
]
}
}
},
"required": [
"id"
]
}
},
"master_record_fields": {
"type": "array",
"description": "Array of master record field configurations",
"maxItems": 100,
"items": {
"type": "object",
"description": "Master record field configuration",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "API name of the master record field",
"maxLength": 100
},
"_data": {
"oneOf": [
{
"type": "array",
"description": "Array of file/image upload data for master record",
"maxItems": 50,
"items": {
"type": "object",
"description": "File or image upload information for master record",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the file or image",
"pattern": "^[0-9]+$",
"maxLength": 50
}
},
"required": [
"id"
]
}
},
{
"type": "null",
"description": "No file data (will delete all files for this field)"
}
]
}
},
"required": [
"api_name"
]
}
}
},
"required": [
"data"
]
}
}
},
"required": [
"merge"
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Records merged successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Response for successful merge operation",
"additionalProperties": false,
"properties": {
"merge": {
"type": "array",
"description": "Array of merge operation results",
"maxItems": 1,
"items": {
"type": "object",
"description": "Individual merge operation result",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Success code for the merge operation",
"enum": [
"SUCCESS"
]
},
"details": {
"type": "object",
"description": "Details of the successful merge operation",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "ID of the merged record",
"pattern": "^[0-9]+$",
"maxLength": 50
}
},
"required": [
"id"
]
},
"message": {
"type": "string",
"description": "Success message for the merge operation",
"maxLength": 500
},
"status": {
"type": "string",
"description": "Status of the merge operation",
"enum": [
"success"
]
}
},
"required": [
"code",
"details",
"message",
"status"
]
}
}
},
"required": [
"merge"
]
}
}
}
},
"201": {
"description": "Merge operation initiated - may be completed synchronously or scheduled asynchronously",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"description": "Response when merge operation is completed or scheduled",
"additionalProperties": false,
"properties": {
"merge": {
"type": "array",
"description": "Array of merge operation results",
"maxItems": 1,
"items": {
"oneOf": [
{
"type": "object",
"description": "Successful merge completion response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
"description": "Success code for completed merge",
"enum": [
"SUCCESS"
]
},
"details": {
"type": "object",
"description": "Details of the completed merge operation",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "ID of the merged record",
"pattern": "^[0-9]+$",
"maxLength": 50
}
},
"required": [
"id"
]
},
"message": {
"type": "string",
"description": "Success message for the merge operation",
"maxLength": 500
},
"status": {
"type": "string",
"description": "Status of the merge operation",
"enum": [
"success"
]
}
},
"required": [
"code",
"details",
"message",
"status"
]
},
{
"type": "object",
"description": "Scheduled merge operation response",
"additionalProperties": false,
"properties": {
"code": {
"type": "string",
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-find-and-merge-openapi.json