Mass Delete Records

Purpose

To delete the records of a module in bulk. You can delete up to 50,000 records in a custom view or delete up to 500 records using their record IDs in an API call.

Endpoints

  • POST /{module_api_name}/actions/mass_delete

Request Details

Request URL

{api-domain}/crm/{version}/{module_API_name}/actions/mass_delete

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Meetings, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Services, Appointments, and custom modules

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.mass_delete.DELETE
(or)
ZohoCRM.mass_delete.{module_name}.DELETE

Possible module names

leads, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, services, appointments, and custom

Note

  • You can delete up to 50,000 records from a custom view and 500 records using their record IDs in a single API call.
  • When you specify the record IDs, and one or more of them have invalid values, only those records will not be deleted.

Sample Request

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

Request JSON Keys

  • cvidstring, mandatory when you do not include "ids"

    The unique ID of the custom view whose records you want to delete. Use the Custom View Metadata API to get the ID of the custom view.

    Note

    The cvid key is supported for mass delete via API in the following editions:

    • Enterprise
    • Ultimate
    • CRM Plus
    • Zoho One Enterprise
  • idsJSON object, mandatory when you do not include "cvid"

    The unique IDs of the records you want to delete. Use the Get Records API to get the record IDs.

  • territoryJSON object, optional

    The unique ID of the territory whose records you want to delete. Use the Get Territories API to get the ID of the territory.

    include_childBoolean, optional

    Represents whether you want to delete records from the child territories.

Sample Input with Record IDs

Copied{
    "ids":["3652397000006064023","3652397000003852074"]
}

Sample Request for Record IDs in the Input

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "3652397000006064023"
            },
            "message": "record is deleted",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "3652397000003852074"
            },
            "message": "record is deleted",
            "status": "success"
        }
    ]
}

Sample Input with CVID and Territory

Copied{
    "cvid": "3652397000000538003",
    "territory": {
        "id": "3652397000007622003",
        "include_child": true
    }
}

Response JSON Keys

  • code

    Represents whether the API was a success or not.

  • details
    • When you give CVID, the response contains the ID of the mass delete job. Use this ID in the Mass Delete Status API.
    • When you give the record IDs in the request body, this key contains the record ID that was deleted.

Possible Errors

  • INVALID_DATAHTTP 400

    The record ID is invalid.
    Resolution: Provide valid IDs. Use the Get Records API to get the record IDs.

  • ALREADY_SCHEDULEDHTTP 400

    You are trying to mass delete when a mass delete job is already running.
    Resolution: You can schedule only one mass delete job at a time. Wait for the already scheduled job to finish before scheduling another one.

  • 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.

  • AUTHORIZATION_FAILEDHTTP 400

    You do not have sufficient permission to mass delete records.
    Resolution: Contact your system administrator.

  • 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.

  • NOT_APPROVEDHTTP 400

    The record you are trying to delete is unapproved.
    Resolution: You can delete only approved records.

  • NOT_SUPPORTEDHTTP 400

    The module is not supported to be mass-deleted through an API.
    Resolution: Contact your administrator.

  • AUTHENTICATION_FAILUREHTTP 401

    You have not authenticated the API call with a valid access token.
    Resolution: Include a valid access token in the request header to authenticate the API call.

  • 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 ZohoCRM.modules.{module_name}.{operation_type}. Refer to the Possible module names and Possible operation types sections for details.

  • NO_PERMISSIONHTTP 403

    You do not have permission to delete the record or to mass delete.
    Resolution: Contact your administrator to obtain permission to delete or mass delete records from the module.

  • 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 for Input with CVID and Territory

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "job_id": "3652397000009565021"
            },
            "message": "mass delete scheduled successfully",
            "status": "success"
        }
    ]
}