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

Request Details

Request URL

{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

scope= ZohoCRM.settings.recycle_bin.READ

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v6/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, deleted_time, deleted_by
Default value: deleted_time
sort_orderstring, optional
To sort the available list of records in either ascending or descending order.
Possible values: asc - ascending order, desc - descending order.
Default value: desc
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.
JSON keys in filters param:
- 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 on the right 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_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 request URL section above.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have the required OAUTH SCOPE. Create a new client with valid scope. Refer to scope section above for more details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team.
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. Specify a valid request method. Refer to endpoints section above.
INVALID_DATAHTTP 403
- 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.

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
    }
}