Get Recycle Bin Records

Purpose

To fetch the records in the Recycle Bin in your CRM account. You can fetch upto 200 records in a single API call.

Endpoints

GET /settings/recycle_bin
GET /settings/recycle_bin/{record_ID}

Request Details

Request URL

To fetch all records:
{api-domain}/crm/{version}/settings/recycle_bin

To fetch a specific record by ID:
{api-domain}/crm/{version}/settings/recycle_bin/{record_ID}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.recycle_bin.READ

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/recycle_bin?filters=%7B%22group_operator%22%3A%22AND%22%2C%22group%22%3A%5B%7B%22field%22%3A%7B%22api_name%22%3A%22display_name%22%7D%2C%22comparator%22%3A%22contains%22%2C%22value%22%3A%22John%22%7D%2C%7B%22field%22%3A%7B%22api_name%22%3A%22module%22%7D%2C%22comparator%22%3A%22equal%22%2C%22value%22%3A%22Leads%22%7D%5D%7D"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Parameters

sort_bystring, optional
To sort the available list of records based on the given field.
Possible values:
display_name - to sort by the display name of the record
deleted_time - to sort by the deleted time of the record. This is the default value.
deleted_by - to sort by the deleted_by value of the record
sort_orderstring, optional
To sort the available list of records in either ascending or descending order.
Possible values:
asc - ascending order
desc - descending order. This is the default value.
idsstring, optional
To retrieve specific records based on their unique ID.
Possible values: Valid unique IDs of records. Example: 4150868000001944196
pageinteger
To get the list of records from the respective pages.
Possible values: Positive integer values only.
Default value: 1
per_pageinteger
To get the list of records available per page. The maximum possible value is 200.
Possible values: Positive integer values only.
Default value: 200
filtersJSON object, optional
To specify conditions for retrieving records from the recycle bin, using logical operators and comparators to filter by fields such as display name, module, deleted by, and deleted time.
Note : Make sure to encode the filters parameter value before making the API call.
- group_operator string, optional
  Defines how multiple conditions are combined. The only supported group_operator is AND.
- groupJSON array, mandatory
  An array of filter conditions, where each condition specifies the field, comparator and value.
  - fieldJSON object
    Represents the field by which the records should be filtered. Refer to the Filter Attributes section to know the possible values.
  - comparatorstring
    Represents the comparator operator, such as equal, not_equal, contains, etc. Refer to the Filter Attributes section to know the possible values for each field.
  - valuestring/JSON object
    Represents the value to compare the field against. This can be a string or a JSON object, depending on the field. Refer to the sample section for more details.
Filter Attributes:
- display_name
  The display name of the record. The conditions that can be applied for display_name are equal, not_equal, contains, not_contains, starts_with, and ends_with.
- module
  The API name of the module. Records from this module in the recycle bin will be fetched. The conditions that can be applied for module are equal and not_equal
- deleted_by
  The name of the user who deleted the record. The conditions that can be applied for deleted_by are equal, not_equal, contains, not_contains, starts_with, and ends_with.
- deleted_time
  The date and time the record was deleted, in ISO 8601 DateTime format. The conditions that can be applied for deleted_time are equal, not_equal, greater_than, and less_than.

Note

When you include the record id in the URL, it takes the highest precedence over ids and filters parameters. If the record ID is included in the URL, any filters or ids parameters will be ignored.
The ids parameter has precedence over the filters parameter. If both ids and filters are included, only the ids parameter will be considered.
You can retrieve up to 200 records in a single API call. If there are more than 200 records in the Recycle Bin, use the page parameter to retrieve them.
The more_records key in the response will be set to true if there are more records available, beyond what was returned in the current response. In that case, use the page parameter to retrieve them in batches.

Sample filter parameter value

Copied{
  "group_operator": "AND",
  "group": [
    {
      "field": {
        "api_name": "display_name"
      },
      "comparator": "contains",
      "value": "Zane"
    },
    {
      "field": {
        "api_name": "module"
      },
      "comparator": "equal",
      "value": "Contacts"
    },
    {
      "field": {
        "api_name": "deleted_by"
      },
      "comparator": "equal",
      "value": [
        {
          "id": "111111000000050305",
          "name": "Patricia Boyle"
        }
      ]
    },
    {
      "field": {
        "api_name": "deleted_time"
      },
      "comparator": "greater_than",
      "value": "2022-12-01T01:00:00+05:30"
    }
  ]
}

Response JSON Keys

ownerJSON object
The owner details of the record. This includes the name and the id of the owner.
moduleJSON object
The details of the parent module of the deleted record.
deleted_byJSON object
The details of the user who deleted the record.
idstring
The unique ID of the record.
display_namestring
The display name of the record.
deleted_timestring
The deleted time of the record.

Note

You will receive a No Content (204) response in the following cases:
- The Recycle Bin is empty.
- An invalid record ID is specified.
- The record is not in the Recycle Bin.

Possible Errors

INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP GET method to make this API call. Any other request method will result in this error.
INVALID_DATAHTTP 400
- The given group operator not supported. Only 'AND' operator is supported
  Resolution: Construct the filters parameter value with AND group operator.
- The given API name seems to be invalid
  Resolution: Specify valid API names for the fields in the filters parameter.
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 required scopes for this API. Refer to the Scope section at the beginning of this page for the list of required scopes.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the request URL section at the beginning of this page for more details.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "recycle_bin": [
        {
            "owner": {
                "name": "Patricia Boyle",
                "id": "4876876000000327001"
            },
            "module": {
                "api_name": "Leads",
                "id": "4876876000000002175"
            },
            "deleted_by": {
                "name": "Patricia Boyle",
                "id": "4876876000000327001"
            },
            "id": "4876876000007018006",
            "display_name": "John Doe",
            "deleted_time": "2024-07-23T15:37:52+05:30"
        }
    ],
    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}