Enables users to update a specific field value across multiple records within a CRM module.
{
"openapi": "3.1.0",
"info": {
"title": "Mass Update API",
"description": "Enables users to update a specific field value across multiple records within a CRM module.",
"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"
}
}
}
],
"paths": {
"/{module}/actions/mass_update": {
"post": {
"summary": "Mass Update API",
"description": "Enables users to update a specific field value across multiple records within a CRM module.",
"operationId": "idsUpdate",
"parameters": [
{
"$ref": "#/components/parameters/Module"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"description": "The request body must include `ids`, a list of record identifiers, and `data`, an array of objects mapping field API names to their new values.",
"type": "object",
"properties": {
"data": {
"description": "An array of objects mapping field API names to their new values.",
"type": "array",
"items": {
"description": "Objects mapping field API names to their new values.",
"type": "object",
"additionalProperties": true
},
"maxItems": 1
},
"ids": {
"description": "Record ids",
"type": "array",
"items": {
"description": "Record id",
"type": "string",
"pattern": "^[0-9]+$",
"format": "int64"
},
"maxItems": 500
}
},
"additionalProperties": false,
"required": [
"data",
"ids"
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Indicates that the mass update operation was completed successfully",
"content": {
"application/json": {
"schema": {
"description": "Schema for a successful mass update response",
"type": "object",
"properties": {
"data": {
"description": "Array containing the response for each record",
"type": "array",
"items": {
"description": "Response indicating a successful record update",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Indicates the result of the operation with a response code",
"enum": [
"SUCCESS"
]
},
"details": {
"description": "Details of the record that was updated",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Record id",
"pattern": "^[0-9]+$",
"format": "int64"
},
"Modified_Time": {
"type": "string",
"format": "date-time",
"description": "The date and time when the mass update operation was performed"
},
"Modified_By": {
"description": "The user who performed the mass update operation",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "User id",
"pattern": "^[0-9]+$",
"format": "int64"
},
"name": {
"type": "string",
"description": "Name displayed for the user who made the modification",
"format": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"name"
]
},
"Created_By": {
"description": "The user who originally created the record",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Numeric string identifier for the creating user",
"pattern": "^[0-9]+$",
"format": "int64"
},
"name": {
"type": "string",
"description": "Name of the user who created the record",
"format": "string"
}
},
"additionalProperties": false,
"required": [
"id",
"name"
]
},
"Created_Time": {
"type": "string",
"format": "date-time",
"description": "The date and time when the record was originally created"
}
},
"additionalProperties": false,
"required": [
"id",
"Modified_Time",
"Modified_By",
"Created_By",
"Created_Time"
]
},
"message": {
"type": "string",
"description": "success message",
"format": "string"
},
"status": {
"type": "string",
"description": "Indicates the status of the operation",
"enum": [
"success"
]
}
},
"additionalProperties": false,
"required": [
"code",
"details",
"message",
"status"
]
},
"maxItems": 500
}
},
"additionalProperties": false,
"required": [
"data"
]
}
}
}
},
"400": {
"description": "Responses for mass update errors",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"description": "Returned when the requested module is not supported, such as Services or Appointments modules",
"properties": {
"code": {
"description": "Invalid module",
"type": "string",
"enum": [
"INVALID_MODULE"
]
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "error",
"type": "string",
"enum": [
"error"
]
},
"details": {
"type": "object",
"description": "Invalid module details",
"properties": {
"resource_path_index": {
"type": "integer",
"format": "int32",
"description": "Index of the unsupported resource path segment"
}
},
"additionalProperties": false,
"required": [
"resource_path_index"
]
}
},
"additionalProperties": false,
"required": [
"code",
"message",
"status",
"details"
]
},
{
"type": "object",
"description": "Responses for mass update errors",
"properties": {
"data": {
"type": "array",
"description": "List of error responses corresponding to each record that failed during the mass update",
"items": {
"description": "Types of errors that can occur during mass update",
"oneOf": [
{
"type": "object",
"description": "A required property is missing from the payload",
"properties": {
"code": {
"description": "Mandatory not found",
"type": "string",
"enum": [
"MANDATORY_NOT_FOUND"
]
},
"details": {
"description": "Mandatory not found",
"type": "object",
"properties": {},
"additionalProperties": false
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "Mandatory not found",
"type": "string",
"enum": [
"error"
]
}
},
"additionalProperties": false,
"required": [
"code",
"details",
"message",
"status"
]
},
{
"type": "object",
"description": "Returned when the request data is invalid, including parameter validation, field validation, or type mismatches.",
"properties": {
"code": {
"description": "Invalid data",
"type": "string",
"enum": [
"INVALID_DATA"
]
},
"details": {
"type": "object",
"description": "Error details for invalid data",
"properties": {
"id": {
"type": "string",
"description": "Record ID where the validation failed",
"pattern": "^[0-9]+$",
"format": "int64"
},
"limit": {
"type": "integer",
"format": "int32",
"description": "Maximum allowed limit that was exceeded",
"minimum": 1
},
"maximum_length": {
"type": "integer",
"format": "int32",
"description": "Maximum allowed length for the field value",
"minimum": 1
},
"maximum_decimal_place": {
"type": "integer",
"format": "int32",
"description": "Maximum allowed decimal places for the field",
"minimum": 0
},
"range": {
"type": "object",
"description": "Valid range for numeric field values",
"properties": {
"from": {
"type": "integer",
"format": "int64",
"description": "Minimum allowed value (inclusive)"
},
"to": {
"type": "integer",
"format": "int64",
"description": "Maximum allowed value (inclusive)"
}
},
"required": [
"from",
"to"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "Error",
"type": "string",
"enum": [
"error"
]
}
},
"additionalProperties": false,
"required": [
"code",
"details",
"message",
"status"
]
},
{
"type": "object",
"description": "Returned when there is a mapping mismatch between fields, such as a pipeline not containing the specified stage.",
"properties": {
"code": {
"description": "Mapping mismatch error",
"type": "string",
"enum": [
"MAPPING_MISMATCH"
]
},
"details": {
"type": "object",
"description": "Error details for mapping mismatch",
"properties": {
"mapped_field": {
"type": "string",
"description": "The field that has the mapping relationship",
"format": "string"
},
"api_name": {
"type": "string",
"description": "API name of the field that doesn't match the mapping",
"format": "string"
},
"json_path": {
"type": "string",
"description": "JSON path to the mismatched element in the request body",
"format": "string"
}
},
"additionalProperties": false
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "Error",
"type": "string",
"enum": [
"error"
]
}
},
"additionalProperties": false,
"required": [
"code",
"details",
"message",
"status"
]
},
{
"type": "object",
"description": "Returned when the requested operation or module is not supported. Service and appointment modules are not supported",
"properties": {
"code": {
"description": "Invalid module. Services and Appointments",
"type": "string",
"enum": [
"NOT_SUPPORTED",
"INVALID_MODULE"
]
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "error",
"type": "string",
"enum": [
"error"
]
},
"details": {
"type": "object",
"description": "Feature not supported",
"additionalProperties": false,
"required": [
"resource_path_index"
]
}
},
"additionalProperties": false,
"required": [
"code",
"message",
"status",
"details"
]
}
]
},
"maxItems": 500
}
},
"required": [
"data"
],
"additionalProperties": false
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.mass_update.UPDATE"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.mass_update.Leads.UPDATE"
]
}
]
},
"get": {
"summary": "Retrieve the status of a mass update job",
"description": "Retrieves the current status and progress metrics of an asynchronous mass update job initiated via POST /crm/v8/\\{module\\}/actions/mass_update. Returns record counts and current job state.",
"operationId": "getMassUpdateStatus",
"parameters": [
{
"$ref": "#/components/parameters/Module"
},
{
"$ref": "#/components/parameters/JobId"
}
],
"responses": {
"200": {
"description": "Successfully retrieved the mass update job status, including current state and record processing counts.",
"content": {
"application/json": {
"schema": {
"description": "Successfully retrieved the mass update job status, including current state and record processing counts.",
"type": "object",
"properties": {
"data": {
"description": "Successfully retrieved the mass update job status, including current state and record processing counts.",
"type": "array",
"items": {
"description": "Contains the mass update job status, including Status, Failed_Count, Updated_Count, Not_Updated_Count, and Total_Count.",
"type": "object",
"properties": {
"Status": {
"type": "string",
"description": "Current state of the mass update job",
"enum": [
"COMPLETED",
"SCHEDULED",
"QUEUED",
"RUNNING",
"SUSPENDED",
"FAILED"
]
},
"Failed_Count": {
"type": "integer",
"format": "int32",
"description": "Number of records that failed to update due to validation or other errors"
},
"Updated_Count": {
"type": "integer",
"format": "int32",
"description": "Number of records successfully updated"
},
"Not_Updated_Count": {
"type": "integer",
"format": "int32",
"description": "Number of records pending update or skipped"
},
"Total_Count": {
"type": "integer",
"format": "int32",
"description": "Total number of records submitted for mass update"
}
},
"required": [
"Failed_Count",
"Updated_Count",
"Total_Count",
"Not_Updated_Count",
"Status"
],
"additionalProperties": false
},
"maxItems": 1
}
},
"required": [
"data"
],
"additionalProperties": false
}
}
}
},
"400": {
"description": "Failed to retrieve mass update job status due to invalid parameters or a missing job",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"description": "This response is returned when the required parameter `job_id` is missing",
"properties": {
"code": {
"description": "Mandatory not found",
"type": "string",
"enum": [
"MANDATORY_NOT_FOUND"
]
},
"details": {
"description": "Name of the missing parameter",
"type": "object",
"additionalProperties": false
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "status code",
"type": "string",
"enum": [
"error"
],
"format": "string"
}
},
"required": [
"code",
"details",
"message",
"status"
],
"additionalProperties": false
},
{
"type": "object",
"description": "Invalid job id",
"properties": {
"code": {
"description": "Invalid job id",
"type": "string",
"enum": [
"INVALID_DATA"
]
},
"details": {
"description": "Name of the invalid parameter",
"type": "object",
"additionalProperties": false
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "status code",
"type": "string",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"message",
"status"
],
"additionalProperties": false
},
{
"type": "object",
"description": "Returned when the requested module is not supported, such as the Functions module",
"properties": {
"code": {
"description": "Invalid module",
"type": "string",
"enum": [
"INVALID_MODULE"
]
},
"message": {
"type": "string",
"description": "error message",
"format": "string"
},
"status": {
"description": "error code",
"type": "string",
"enum": [
"error"
]
},
"details": {
"description": "resource path index",
"type": "object",
"required": [
"resource_path_index"
],
"additionalProperties": false
}
},
"required": [
"code",
"message",
"status",
"details"
],
"additionalProperties": false
}
]
}
}
}
}
},
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.mass_update.READ"
]
},
{
"iam-oauth2-schema": [
"ZohoCRM.mass_update.Leads.READ"
]
}
]
}
}
},
"components": {
"parameters": {
"Module": {
"name": "module",
"in": "path",
"required": true,
"description": "Specifies the CRM module for the mass update operation. Note: Module names are case-sensitive.",
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zoho-crm/refs/heads/main/openapi/zoho-crm-mass-update-openapi.json