Zoho: Delete records in bulk by record I Ds or Custom View

← Mass delete operations · Get started

Operation zoho.massdelete

Provider route: POST /crm/v8/{module}/actions/mass_delete. 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["massDelete"]["massDelete"]>[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.massDelete.massDelete(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_delete.mass_delete(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, Services, Appointments Minimum length: 1
body	object	Required within parent	Specify either a list of record IDs or a Custom View ID to identify the records to delete. Use the territory property to filter by territory when using a Custom View ID. Additional keys: not allowed
body.cvid	string	Optional	Specify the unique ID of the Custom View for which you want to delete records. Use the [Get Custom Views](custom_views.yaml#$.paths./settings/custom_views.get) API for valid values. > Note: > The cvid key is supported for mass delete via API in the following editions: > - Enterprise > - Ultimate > - CRM Plus > - Zoho One Enterprise Format: string Pattern: ^[0-9]+$
body.ids	array	Optional	Specify the list of record IDs to delete. Use the [Get Records API](record.yaml#$.paths./{module}.get) to get the valid records ID. Maximum items: 500 Minimum items: 1
body.ids[]	string	Each item	Each string represents a unique record ID to delete. Format: int64
body.territory	object	Optional	The unique ID of the territory whose records you want to delete. This key is valid only when you provide a custom view ID. Additional keys: not allowed
body.territory.id	string	Required within parent	Specify the unique ID of the territory for which you want to delete records. Use the [Get Territories API](territories.yaml#$.paths./settings/territories.get) to get the ID of the territory. Format: string Pattern: ^[0-9]+$
body.territory.include_child	boolean	Optional	Specify whether to include records from child territories in the delete operation. Possible values: true - Include records from child territories. false - Restrict the delete operation to records in the specified territory only.
body (anyOf 1)	object	Alternative	Specify record IDs to delete in bulk. This variant requires the ids array and does not allow cvid or territory. Additional keys: not allowed
body (anyOf 1).ids	array	Required within parent	Specify the list of record IDs to delete. Use the [Get Records API](record.yaml#$.paths./{module}.get) to get the valid record values. Maximum items: 500 Minimum items: 1
body (anyOf 1).ids[]	string	Each item	Specify a unique record ID to delete. Format: string Pattern: ^[0-9]+$
body (anyOf 2)	object	Alternative	Specify a Custom View ID to delete all records from that view. You can also include a territory filter if required. If cvid is provided the API does not accept the ids array. Additional keys: not allowed
body (anyOf 2).cvid	string	Required within parent	Specify the unique ID of the Custom View for which you want to delete records. Refer to the [Get Custom Views](custom_views.yaml#$.paths./settings/custom_views.get) resource for valid values. Format: string Pattern: ^[0-9]+$
body (anyOf 2).territory	object	Optional	Specify the territory filter to restrict the delete operation to records within a specific territory. Only valid when using cvid. Additional keys: not allowed
body (anyOf 2).territory.id	string	Required within parent	Specify the unique ID of the territory for which you want to delete records. Refer to the [Get Territories](territories.yaml#$.paths./settings/territories.get) resource for valid values. Format: string Pattern: ^[0-9]+$
body (anyOf 2).territory.include_child	boolean	Optional	Specify whether to include records from child territories in the delete operation. Possible values: true - Include records from child territories. false - Restrict the delete operation to records in the specified territory only.

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 success response payload for a mass delete operation. Additional keys: not allowed
$ (anyOf 1).data	array	Required within parent	Contains the array of success responses for record deletions or batch job scheduling. Maximum items: 500 Minimum items: 1
$ (anyOf 1).data[]	JSON	Each item	Represents an individual success response for either a record deletion or a scheduled batch delete job.
$ (anyOf 1).data[] (anyOf 1)	object	Alternative	Represents the success response for a record deleted synchronously, including the record ID in the details. Additional keys: not allowed
$ (anyOf 1).data[] (anyOf 1).code	string	Required within parent	Represents the success code for the response. Must equal: SUCCESS
$ (anyOf 1).data[] (anyOf 1).details	object	Required within parent	Contains the details of the deleted record, including the record ID. Additional keys: not allowed
$ (anyOf 1).data[] (anyOf 1).details.id	string	Required within parent	Represents the ID of the deleted record. Format: string Pattern: ^[0-9]+$
$ (anyOf 1).data[] (anyOf 1).message	string	Required within parent	Represents the success message for the response. Must equal: record is deleted
$ (anyOf 1).data[] (anyOf 1).status	string	Required within parent	Represents the status of the response. Must equal: success
$ (anyOf 1).data[] (anyOf 2)	object	Alternative	Represents the success response when a mass delete job is scheduled asynchronously, including the job ID in the details. Additional keys: not allowed
$ (anyOf 1).data[] (anyOf 2).code	string	Required within parent	Represents the success code for the response. Must equal: SUCCESS
$ (anyOf 1).data[] (anyOf 2).details	object	Required within parent	Contains the details of the scheduled batch delete job, including the job ID. Additional keys: not allowed
$ (anyOf 1).data[] (anyOf 2).details.job_id	string	Required within parent	Represents the unique ID of the scheduled mass delete job. Use this ID with the [Mass Delete Status API](mass_delete.yaml #$.paths./{module}/actions/mass_delete.get) to track the job progress. Format: string Pattern: ^[0-9]+$
$ (anyOf 1).data[] (anyOf 2).message	string	Required within parent	Represents the success message for the response. Must equal: mass delete scheduled successfully
$ (anyOf 1).data[] (anyOf 2).status	string	Required within parent	Represents the status of the response. Must equal: success
$ (anyOf 2)	object	Alternative	Represents the multi-status response payload when some records were deleted and others failed validation. Additional keys: not allowed
$ (anyOf 2).data	array	Required within parent	Contains the array of per-record results for the mass delete operation. Each item independently indicates success or failure for the corresponding record. Maximum items: 500 Minimum items: 1
$ (anyOf 2).data[]	JSON	Each item	Represents an individual record result, independently indicating success or failure for that record.
$ (anyOf 2).data[] (anyOf 1)	object	Alternative	Represents the success entry for a record that was successfully deleted in the multi-status response. Additional keys: not allowed
$ (anyOf 2).data[] (anyOf 1).code	string	Required within parent	Represents the success code for the response. Must equal: SUCCESS
$ (anyOf 2).data[] (anyOf 1).details	object	Required within parent	Contains the details of the successfully deleted record, including the record ID. Additional keys: not allowed
$ (anyOf 2).data[] (anyOf 1).details.id	string	Required within parent	Represents the ID of the successfully deleted record. Format: string Pattern: ^[0-9]+$
$ (anyOf 2).data[] (anyOf 1).message	string	Required within parent	Represents the success message for the response. Must equal: record is deleted
$ (anyOf 2).data[] (anyOf 1).status	string	Required within parent	Represents the status of the response. Must equal: success
$ (anyOf 2).data[] (anyOf 2)	object	Alternative	Represents the error entry for a record that failed deletion in the multi-status response. Additional keys: not allowed
$ (anyOf 2).data[] (anyOf 2).code	string	Required within parent	Represents the error code for the response. Known values: INVALID_DATA
$ (anyOf 2).data[] (anyOf 2).details	object	Required within parent	Contains the details of the record that failed deletion, including the record ID. Additional keys: not allowed
$ (anyOf 2).data[] (anyOf 2).details.id	string	Required within parent	Represents the ID of the record that failed deletion. Format: string Pattern: ^[0-9]+$
$ (anyOf 2).data[] (anyOf 2).message	string	Required within parent	Represents the error message describing the reason for the deletion failure. Format: string
$ (anyOf 2).data[] (anyOf 2).status	string	Required within parent	Represents the status of the response. Must equal: error

Policy, approvals and errors

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