Mass Update Records
The mass update feature allows you to update the values of specific fields for multiple records in territories or custom views in a module. This API is useful when you want to update the same field for all records in a module, territory, or a custom view.
In this API, the input contains the API names of the fields whose values you want to update and the record IDs, CVIDs(custom view IDs), or territory ID.
You can update up to 50,000 records using this API.
Mass update of records happens in two ways:
- Scheduler type: When you specify a custom view ID and territory ID, a job is scheduled in the background and the system returns a "job_id". Use this job_id in the Get Mass Update Status API to get the status of the job. You can update a maximum of 50,000 records in this type.
- Non-scheduler type: When you specify the record IDs, system updates the records instantly. You can update a maximum of 500 records in a single API call in this type of mass update.
Mass Update Records
Purpose
To schedule mass update of records.
Endpoints
- POST /{module_API_name}/actions/mass_update
Request Details
Request URL
{api-domain}/crm/{version}/{module_API_name}/actions/mass_update
Supported modules
Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Calls, Meetings, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, and Custom
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
ZohoCRM.mass_update.UPDATE
(or)
ZohoCRM.mass_update.{module_name}.UPDATE
Possible module names
leads, accounts, contacts, deals, campaigns, tasks, calls, meetings, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, and custom
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/Accounts/actions/mass_update"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X POSTCopiedrecordIDList = List();
recordIDList.add("692969000000416006");
recordIDList.add("692969000000287129");
recordIDList.add("692969000000287038");
input1 = Map();
input1.put("Lead_Source", "Advertisement");
inputList = List();
inputList.add(input1);
params = Map();
params.put("data", inputList);
params.put("over_write", true);
params.put("ids", recordIDList);
response = invokeurl
[
url :"https://www.zohoapis.com/crm/v8/Deals/actions/mass_update"
type :POST
parameters: params.toString()
connection:"crm_oauth_connection"
];
info response;Show full
Show less
In the request, "@input.json" contains the sample input data.
Request JSON Keys
- cvidstring, mandatory when custom view fields or territory fields are updated
The custom view ID whose records you want to mass update.
Note
The cvid key is supported for mass update via API in the following editions:
- Enterprise
- Ultimate
- CRM Plus
- Zoho One Enterprise
- over_writeboolean, optional
Used when updating a multi-select picklist field.
Possible values :- false: adds the specified value to the picklist. Default is false.
- true: replaces all the multi-select picklist values with the value specified for mass update.
- territoryJSON object, mandatory, when territory fields are updated
Used to update records in that territory.
Possible keys :- include_child (boolean): Boolean field to indicate whether you want to mass update the child territory records as well. Default is false.
- id (string): The territory ID to update the records in that territory.
- idsJSON array, mandatory, when records are updated by IDs
Specify the IDs of the records you want to mass update.
Note
- Scheduler type(using record IDs):
- You can mass update a maximum of 50,000 records in a single API call.
- Automation rules are triggered automatically when the record count is less than 1000. When the record count is greater than 1000, automation rules do not get triggered.
- If some of the records have invalid data, only those records will not be processed in the API call.
- Non-scheduler type(using CVID and territory ID):
- You can mass update a maximum of 500 records in a single API call.
- Automation rules such as approvals, blueprints, and workflows are triggered automatically.
- When you want to mass update records in a territory, you must specify the custom view ID.
- You cannot mass update Email, lookup fields, layout fields, multi-line fields, and line items.
- You can mass update up to three fields in the Deals module and only one field in all other modules in a single API call.
Sample Input
CopiedWith cvid and Territory ID
{
"data": [
{
"Industry": "Education"//field to be updated
}
],
"cvid": "554023000000091515", //custom view ID to mass update records in that custom view
"territory": {
"id": "554023000000430409",//ID of the territory to mass update records in that territory
"include_child": true //include child territory records for mass updation
}
}
With Record IDs in the Input
{
"data": [
{
"Lead_Source": "Advertisement",
"Type": "Existing Business",
"Languages_Known": [
"English",
"Spanish"
]
}
],
"over_write": true,
"ids": [
"554023000000497007",
"554023000000497021"
]
}In the sample input with record IDs, "Languages_Known" is a custom multi-select picklist in the Deals module.
Response JSON Keys
- codestring
Indicates the status of mass update.
- detailsJSON object
Specifies the "job_id" (for scheduler type), modified time, and the name and ID of the user who modified the record (for non-scheduler type).
- created_timeDate and time in the ISO8601 format
Specifies the time period when the record was created.
- idstring
Specifies the ID of the record that was updated.
- Created_ByJSON Object
Specifies the name and ID of the user that created the record.
- messagestring
Specifies if the record is updated or the reason for error, if any.
- statusstring
Specifies the status of the record as updated, error etc.
Possible Errors
- ALREADY_SCHEDULEDHTTP 202
Already a Mass Action scheduler is running for the given custom view ID.
Resolution: Wait for the scheduler to finish or schedule another job for another set of records. - INVALID_DATAHTTP 400
You have not given a request body.
Resolution: Refer to the Request JSON Keys section for the list of input keys. - INVALID_DATAHTTP 400
Number of fields to be mass updated has exceeded the allowed limit for that module.
Resolution: You can mass update up to a maximum of three fields in the Deals module and only one field in other modules. - INVALID_DATAHTTP 400
The specified field is not found in the module or it is not allowed for mass update.
Resolution: Contact your system administrator. - INVALID_DATAHTTP 400
The specified field is used as primary in a layout rule or is associated with a validation rule.
Resolution: You cannot mass update a primary field that is associated with a layout rule or a validation rule. - INVALID_DATAHTTP 400
The specified field is made invisible or is inaccessible to you.
Resolution: Contact your system administrator. - INVALID_DATAHTTP 400
The record ID, CVID, or territory ID specified is invalid.
Resolution: Specify valid IDs in the input. - INVALID_DATAHTTP 400
In the non-scheduler type request, one or more record IDs is invalid. The valid record IDs get updated, and the invalid IDs throw an error.
Resolution: Specify valid record IDs in the input. - 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. - AUTHORIZATION_FAILEDHTTP 400
You do not have sufficient permission to mass update records.
Resolution: Contact your system administrator. - RECORD_LOCKEDHTTP 400
You cannot update record that is not approved yet.
Resolution: Please wait until the Zia image, merge duplicates or other approval processes are complete and try again. - RECORD_LOCKEDHTTP 400
You cannot mass update as the record is locked.
Resolution: Please wait until the record is unlocked. - NOT_APPROVEDHTTP 400
You cannot update the record as it is not approved yet.
Resolution:- Case 1: If the record is in the rejected state due to Zia image validation, either upload a new image (or) delete the failed image and, resubmit the record to Zia image validation.
- Case 2: If the record is in Zia record approval, the system will not allow you to update the images of the record until the reviewer approves or rejects the record.
- CANNOT_PROCESSHTTP 400
The record is in stop processing.
Resolution: Contact your system administrator. - RECORD_IN_BLUEPRINTHTTP 400
The record is in blueprint.
Resolution: Wait for the record to complete all blueprint transitions before updating it. - MANDATORY_NOT_FOUNDHTTP 400
You have not specified either the CVID or the record IDs.
Resolution: You must specify either the CVID or the record IDs in the input body. - CANNOT_PERFORM_ACTIONHTTP 400
You do not have permission to perform any action on the record.
Resolution: Contact your system administrator. - LIMIT_EXCEEDEDHTTP 400
Number of records that can be mass updated has exceeded the maximum allowed limit of 50000.
Resolution: Schedule another mass update job for another set of records. - NOT_APPROVEDHTTP 400
The record with the specified ID is not approved.
Resolution: Wait for the record to be approved or contact your system administrator. - NO_RECORDS_FOUNDHTTP 400
There are no records in the specified custom view.
- INVALID_MODULEHTTP 400
You have either specified an invalid module API name, there is no tab permission, or the module is removed from the list of available modules.
Resolution: Use the Modules API to get the API name of the module. If you have no tab permission or the module is removed, contact your system administrator. - 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 scope mentioned in the Scope section. - NO_PERMISSIONHTTP 403
You do not have permission to either edit the field, or have no access to the custom view.
Resolution: Contact your system administrator. - INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the Request URL section for the right URL. - INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.
Sample Response
CopiedResponse for scheduler type
{
"data": [
{
"code": "SUCCESS",
"details": {
"job_id": "554023000000506003"
},
"message": "mass update scheduled successfully",
"status": "success"
}
]
}
Response for non-scheduler type (with record IDs)
{
"data": [
{
"code": "SUCCESS",
"details": {
"Modified_Time": "2021-03-03T12:17:00+05:30",
"Modified_By": {
"name": "Patricia boyle",
"id": "554023000000497007"
},
"Created_Time": "2021-02-26T19:13:56+05:30",
"id": "580845000003654076",
"Created_By": {
"name": "Patricia Boyle",
"id": "580845000000242009"
}
},
"message": "record updated",
"status": "success"
},
{
"code": "INVALID_DATA",
"details": {
"id": "554023000000497021"
},
"message": "the id given seems to be invalid",
"status": "error"
}
]
}