Mass Delete API

The mass delete feature allows you to delete records in bulk. This API is useful when you want to delete all the records in a territory, or a custom view.

In this API, the input contains the record ids, cvids(custom view IDs), or territory_id.

You can delete up to 50,000 (fifty thousand) records using this API.

Mass delete of records happens in two ways:

  • Scheduler type:

    When you specify 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 request to get the result.

  • Non-scheduler type:

    When you specify the record IDs, system updates the records instantly. You can delete a maximum of 500 records in a single API call in this type of mass delete.

Purpose

To delete records in bulk.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/actions/mass_delete

module_api_name - The API name of the module

Supported modules
Leads, Accounts, Contacts, Deals, Campaigns, Activities, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, and Custom

Request Method

POST

 

Scope

scope=ZohoCRM.mass_delete.{module_name}.DELETE

Possible module names
leads, accounts, contacts, deals, campaigns, activities, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, and custom

Request JSON

AttributeData TypeMandatoryDescription
idsJSON ArrayYes, when the records are deleted by IDsSpecify the IDs of the records you want to mass delete.
cvidStringYes, when the records in a custom view or a territory are deletedThe custom view ID whose records you want to mass delete
territoryJSON ObjectYes, when records in a territory are deletedid - The territory ID to delete the records in that territory
include_child - Boolean field to indicate whether you want to mass delete the child territory records as well.
Default value is false.

Possible Errors

HTTP StatusError CodeMessageReason
200INVALID_DATAThe id given seems to be invalidThe record ID, cvid, or territory ID specified is invalid
200MANDATORY_NOT_FOUNDrequired field not foundNo cvid or record ID is specified in the input
200CANNOT_PERFORM_ACTIONno permission to perform an action on this recordUser does not have permission to perform any action on the record
200ALREADY_SCHEDULEDAlready a Mass Action scheduler is running for the given cvidThe records in the custom view specified are already scheduled for mass delete
200LIMIT_EXCEEDEDRecord count exceededNumber of records that can be mass deleted has exceeded the maximum allowed limit of 50000
200NOT_APPROVEDrecord not approvedThe record with the specified ID is not approved
400NO_RECORDS_FOUNDno record found to deleteThere are no records in the custom view specified
403NO_PERMISSIONpermission deniedUser does not have permission to mass delete records
403NO_PERMISSIONDelete permission not givenUser does not have permission to delete records in that module
403NO_PERMISSIONCustom view not accessibleCustom view is not accessible to the user or the module
Note:
  • You can mass delete a maximum of 500 records in a single API call when you use the non-scheduler type mass delete (i.e with record IDs).

  • You can mass delete a maximum of 50,000 (fifty thousand) records in a single API call when you use the scheduler type mass delete (i.e by specifying the cvid and territory ID).

  • While mass deleting records based on their IDs, if some of the records have invalid data, only those records will not be processed.

  • Use Territories API to get the territory ID and Custom view API to get the cvid.

  • It is mandatory to specify either custom view ID or record IDs in the input.

  • It is mandatory to specify the custom view ID when you want to mass delete records in a territory.

Sample Request Using Record ID

Copiedcurl "https://www.zohoapis.com/crm/v2/Leads/actions/mass_delete"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"