Zoho: Mass update records

← Mass update operations · Get started

Operation zoho.massupdaterecords

Provider route: POST /crm/v8/{module}/actions/mass_update. 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["massUpdate"]["massUpdateRecords"]>[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.massUpdate.massUpdateRecords(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.mass_update.mass_update_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.module	string	Required within parent	One of: Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Calls, Meetings, Cases, Solutions, Products, Vendors, Price_Books, Quotes, Sales_Orders, Purchase_Orders, Invoices, Custom
body	object	Required within parent	Represents the mass update request payload. The payload must include the `data` array along with either `ids` for a synchronous update or `cvid` for an asynchronous scheduled update. `ids` and `cvid` are mutually exclusive. Additional keys: not allowed
body.cvid	string	Optional	Specify the Custom View ID whose matching records must be mass updated. Use `cvid` to schedule an asynchronous background job that processes the records in the Custom View. Use the [Get Custom View API](custom_views.yaml#$.paths./settings/custom_views.get) to get the ID of the requires custom view. The response returns a `job_id` that can be passed to [Get Mass Update Status API](mass_update.yaml#$.paths./{module}/actions/mass_update.get) to track the progress of the scheduled job. > Note: > The cvid key is supported for mass update via API in the following editions: > - Enterprise > - Ultimate > - CRM Plus > - Zoho One Enterprise Format: int64 Pattern: ^[0-9]+$
body.data	array	Required within parent	Specify the array of objects, where each object maps a field’s API name to the new value to be applied across the targeted records. The key must be provided along with either `ids` or `cvid`. Maximum items: 1
body.data[]	object	Each item	Each object maps one or more field API names to the new values to be applied. > Note: > The Deals module allows up to three fields per object; all other supported modules allow only one field per object. > Email, lookup, multi-line, layout, and line item fields cannot be mass updated. Additional keys: allowed
body.ids	array	Optional	Specify the record IDs to be mass updated synchronously. Use `ids` for non-scheduler updates that target a small batch of records and require immediate processing. Use the [Get Records API](record.yaml#$.paths./{module}.get) to get the valid IDs of the required records. > Note: > - You can use either ids key or the cvid key, you cannot use them both in a request. > - 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. Maximum items: 500
body.ids[]	string	Each item	Each string specifies the unique ID of a record to be updated. Format: int64
body.territory	object	Optional	Specify the territory whose records must be mass updated. This key is valid only when you provide a Custom View ID in `cvid`. Additional keys: not allowed
body.territory.id	string	Required within parent	Specify the unique ID of the territory. Use the [Get Territories API](territories.yaml#$.paths./settings/territories.get) to get the ID of the required territory. Format: int64 Pattern: ^[0-9]+$
body.territory.include_child	boolean	Optional	Specify whether to include the records of the child territories in the mass update. Possible values: true - Include the records of the child territories. false - Restrict the mass update to the records in the specified territory only.
body (anyOf 1)	JSON	Alternative	Represents the synchronous variant of the request payload, provided when records are targeted by a list of record IDs. This variant does not accept the `territory` key.
body (anyOf 1).territory	JSON	Optional	Ensures that the `territory` key is not provided along with the `ids` key.
body (anyOf 2)	JSON	Alternative	Represents the scheduled variant of the request payload, provided when records are targeted by a Custom View ID. This variant accepts the optional `territory` key.

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
$ (anyOf 1)	object	Alternative	Represents the response wrapper returned when the mass update operation is accepted, containing one or more outcome entries for the processed records or the scheduled job. Additional keys: not allowed
$ (anyOf 1).data	array	Required within parent	Represents the array that contains one response object per record processed or one entry describing the scheduled job. Maximum items: 500
$ (anyOf 1).data[]	object	Each item	Represents a single response entry, containing either the scheduled job details (when the request was made using `cvid`) or the updated record details (when the request was made using `ids`). Additional keys: not allowed
$ (anyOf 1).data[].code	string	Required within parent	Represents the result code for the individual entry. Known values: SUCCESS
$ (anyOf 1).data[].details	object	Required within parent	Represents additional details about the response. Additional keys: allowed
$ (anyOf 1).data[].details (anyOf 1)	object	Alternative	Represents the scheduler-type details, returned when the mass update is scheduled via a Custom View ID. Contains the `job_id` that can later be used to track the job’s progress using the [Get Mass Update Status API](mass_update.yaml#$.paths./{module}/actions/mass_update.get). Additional keys: not allowed
$ (anyOf 1).data[].details (anyOf 1).job_id	string	Required within parent	Represents the unique ID of the scheduled mass update job. Pass this value as the `job_id` query parameter to [Get Mass Update Status API](mass_update.yaml#$.paths./{module}/actions/mass_update.get) to retrieve the job’s current status and record counts. Format: int64 Pattern: ^[0-9]+$
$ (anyOf 1).data[].details (anyOf 2)	object	Alternative	Represents the non-scheduler-type details, returned when the API processes individual records synchronously. Additional keys: not allowed
$ (anyOf 1).data[].details (anyOf 2).Created_By	object	Required within parent	Represents the user who originally created the record. Additional keys: not allowed
$ (anyOf 1).data[].details (anyOf 2).Created_By.id	string	Required within parent	Represents the unique ID of the user who created the record. Format: int64 Pattern: ^[0-9]+$
$ (anyOf 1).data[].details (anyOf 2).Created_By.name	string	Required within parent	Represents the display name of the user who created the record. Format: string
$ (anyOf 1).data[].details (anyOf 2).Created_Time	string	Required within parent	Represents the date and time, in ISO 8601 format, when the record was originally created. Format: date-time
$ (anyOf 1).data[].details (anyOf 2).Modified_By	object	Required within parent	Represents the user who performed the mass update on the record. Additional keys: not allowed
$ (anyOf 1).data[].details (anyOf 2).Modified_By.id	string	Required within parent	Represents the unique ID of the user who modified the record. Format: int64 Pattern: ^[0-9]+$
$ (anyOf 1).data[].details (anyOf 2).Modified_By.name	string	Required within parent	Represents the display name of the user who modified the record. Format: string
$ (anyOf 1).data[].details (anyOf 2).Modified_Time	string	Required within parent	Represents the date and time, in ISO 8601 format, when the record was last modified by the mass update operation. Format: date-time
$ (anyOf 1).data[].details (anyOf 2).id	string	Required within parent	Represents the unique ID of the record that the mass update operation modified. Format: int64 Pattern: ^[0-9]+$
$ (anyOf 1).data[].message	string	Required within parent	Represents the message describing the result of the operation. Format: string
$ (anyOf 1).data[].status	string	Required within parent	Represents the status of the operation for this entry. Known values: success
$ (anyOf 2)	object	Alternative	Represents the response wrapper returned when a non-scheduler-type mass update results in mixed responses, containing at least one successfully updated record and at least one failed record. Additional keys: not allowed
$ (anyOf 2).data	array	Required within parent	Represents the array that contains one response object per record processed, indicating whether the mass update succeeded or failed for that record. Maximum items: 500 Minimum items: 2
$ (anyOf 2).data[]	object	Each item	Represents a single per-record entry, containing either the details of the updated record or the error that prevented the record from being updated. Additional keys: not allowed
$ (anyOf 2).data[].code	string	Required within parent	Represents the result code for the individual record. Possible values: SUCCESS - The record was updated successfully. MANDATORY_NOT_FOUND - A required property is missing from the payload for the record. INVALID_DATA - The request data is invalid for the record. MAPPING_MISMATCH - The provided value violates a field mapping relationship for the record. RECORD_LOCKED - The record is locked and cannot be updated. CONVERTED_RECORD - The record has already been converted and cannot be updated. Known values: SUCCESS, MANDATORY_NOT_FOUND, INVALID_DATA, MAPPING_MISMATCH, RECORD_LOCKED, CONVERTED_RECORD
$ (anyOf 2).data[].details	object	Required within parent	Represents additional details about the response. For an updated record, it contains the record ID along with its creation and modification details. For a failed record, it contains the details of the failure, such as the ID of the record that could not be updated. Additional keys: allowed
$ (anyOf 2).data[].message	string	Required within parent	Represents the message describing the result of the operation for this record. Maximum length: 255
$ (anyOf 2).data[].status	string	Required within parent	Represents the status of the operation for this record. Possible values: success - The record was updated. error - The record was not updated. Known values: success, error
$ (anyOf 2).data (allOf 1)	JSON	All variants apply	Represents the constraint ensuring that the response contains at least one successfully updated record.
$ (anyOf 2).data (allOf 2)	JSON	All variants apply	Represents the constraint ensuring that the response contains at least one record that failed to update.

Policy, approvals and errors

SDK function policy ID: zoho.massupdaterecords. Catalog operation: massUpdateRecords. 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