Restore Recycle Bin Records

Purpose

To restore one or more deleted records from the Recycle Bin in your Zoho CRM org.

Endpoints

POST /settings/recycle_bin/{record_ID}/actions/restore
POST /settings/recycle_bin/actions/restore

Request Details

Request URL

To restore a specific record by ID:
{api-domain}/crm/{version}/settings/recycle_bin/{record_ID}/actions/restore
To restore multiple records, restore using filters, or restore all records:
{api-domain}/crm/{version}/settings/recycle_bin/actions/restore

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.recycle_bin.UPDATE

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/recycle_bin/4876876000003294168/actions/restore"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @restore.json

Note

When you restore a record from the Recycle Bin, all its associated records in the Recycle Bin will also be restored. For example, if a Lead is restored, its related Notes and Attachments will also be restored.
If the total number of records to be restored exceeds 1000, including the parent record and its associated records, the restore action will be scheduled as a background job. If the total record count is 1000 or fewer, restoration happens immediately.
When restoration is performed using filters, the action is always scheduled, regardless of the number of records that match the filter criteria.
Admin users can restore any record.
Non-admin users can always restore records they own. They can restore others' records only if their profile permits access to those records.

Input JSON

The input JSON is required only when restoring multiple records, restoring records using filters, or restoring all records in the Recycle Bin. No request body is required when restoring a single record. In that case, include the record ID in the request URL itself. For more details, refer to the Request URL section.

idsJSON array, mandatory when restoring specific records
Specify the unique IDs of the records you want to restore from the Recycle Bin, in a comma separated format.
restore_all_recordsBoolean, optional
Set this field to true to restore every record currently in the Recycle Bin. When set to true, this must not be combined with ids or filters. If set to false, you must additionally specify either ids or filters to define what should be restored.
Please note that when restore_all_records is set to true, this operation always schedules a bulk restoration job.
filtersJSON object, mandatory when restoring records based on conditions
Use this field to restore records that match certain filter criteria. Restoration using filters is always scheduled, regardless of the number of matching records.
- group_operatorstring, mandatory
  Specifies how the conditions inside the group array should be combined.
  Possible value: AND.
- groupJSON array, mandatory
  A list of filter conditions.
  Each condition includes:
  - fieldJSON object, mandatory
    Specify the field to filter by. The object must include the API name of the field.
    Possible values: display_name, module, deleted_by, deleted_time
  - comparatorstring, mandatory
    The comparison operator to apply.
    Possible values: equal, not_equal, contains, not_contains, starts_with, ends_with, greater_than, less_than
  - valuestring or JSON object, mandatory
    The value to compare the field against, depending on the field type.

Supported comparators for different fields

Field	Supported Comparators
display_name	equal, not_equal, contains, not_contains, starts_with, ends_with
module	equal, not_equal
deleted_by	equal, not_equal, contains, not_contains, starts_with, ends_with
deleted_time	equal, not_equal, greater_than, less_than

Input rules:

A restore request must specify exactly one restoration mode: ids, filters, or restore_all_records: true. These options are mutually exclusive. Specifying more than one results in an AMBIGUITY_DURING_PROCESSING error.
If restore_all_records is included and set to false, it cannot be used as a restoration mode. In this case, you must explicitly define the restore scope using either ids or filters.

Sample input for restoring specific records

Copied{
    "ids": [
        "4876876000016013030",
        "4876876000015007594"
    ]
}

Sample Response

Copied{
    "recycle_bin": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "4876876000016013030"
            },
            "message": "record restored",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "4876876000015007594"
            },
            "message": "record restored",
            "status": "success"
        }
    ]
}

Sample input to restore all records

Copied{
    "restore_all_records" : true
}

Sample Response

Copied{
    "recycle_bin": [
        {
            "code": "SCHEDULED",
            "details": {},
            "message": "Bulk restoration of records based on filters has been scheduled",
            "status": "success"
        }
    ]
}

One invalid ID and one record scheduled for restoration

If a restore request contains multiple record IDs and one of the IDs is invalid while another valid record (including its child records) exceeds 1000 total records, the API returns a partial success with 202 status code. The invalid ID returns an error and the valid record is scheduled for restoration.

Sample Response : 202 status

Copied{
    "recycle_bin": [
        {
            "code": "INVALID_DATA",
            "details": { "id": "111111000000077729" },
            "message": "the id given seems to be invalid",
            "status": "error"
        },
        {
            "code": "SCHEDULED",
            "details": { "id": "111111000000077734" },
            "message": "record has been scheduled for restoration",
            "status": "success"
        }
    ]
}

One valid ID restored immediately, and one invalid ID

If a restore request includes multiple IDs and one record can be restored immediately (1000 or fewer associated records) while another ID is invalid, the API returns a 207 multi-status response. The valid record is restored, and the invalid ID returns an error.

Sample Response : 207 status

Copied{
    "recycle_bin": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "111111000000077729"
            },
            "message": "record restored",
            "status": "success"
        },
        {
            "code": "INVALID_DATA",
            "details": {
                "id": "1111110000000772734"
            },
            "message": "the id given seems to be invalid",
            "status": "error"
        }
    ]
}

Possible Errors

INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL. Please retry this request with POST method.
AMBIGUITY_DURING_PROCESSINGHTTP 400
Only one among these fields (ids/filters/restore_all_records) should be given for restoration
Resolution: Remove the extra fields from the input JSON and retry the request using only one restoration mode.
EXPECTED_DEPENDENT_FIELD_MISSINGHTTP 400
If restore_all_records is set to false, ids/filters field is required to restore records
Resolution: Add either the ids field or the filters field to the input JSON and retry the request.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have the required OAUTH SCOPE. Generate a new token with the valid scope. Refer to the Scope section for more details.
INVALID_DATAHTTP 403
The id given seems to be invalid
Resolution: Specify valid record IDs.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to the Request URL section for more details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team.

Sample Input to restore records using filters

Copied{
    "filters": {
        "group_operator": "AND",
        "group": [
            {
                "field": {
                    "api_name": "display_name"
                },
                "comparator": "contains",
                "value": "Amazon Marketplace"
            },
            {
                "field": {
                    "api_name": "module"
                },
                "comparator": "equal",
                "value": "Leads"
            }
        ]
    }
}

Sample Response

Copied{
    "recycle_bin": [
        {
            "code": "SCHEDULED",
            "details": {},
            "message": "Bulk restoration of records based on filters has been scheduled",
            "status": "success"
        }
    ]
}