Return a list of cases based on a query.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Returns a lightweight array of authorized Supportbench cases matching the supplied filters.
The endpoint preserves the caller's tenant, role, and division access restrictions. It does not return a response wrapper or total count.
Endpoint
POST https://api.supportbench.net/cases
Send an OAuth bearer token and a JSON request body. All request dates and returned timestamps are UTC.
Request body
Every property is optional. Comma-separated properties may contain one or more IDs or values.
| Property | Type | Description |
|---|---|---|
| cases | string or null | Comma-separated case IDs, for example C-1000,C-1001. |
| companies | string or null | Comma-separated company IDs assigned to the cases. |
| contacts | string or null | Comma-separated primary contact IDs assigned to the cases. |
| status_id | integer or null | Omitted, null, or -1 returns all authorized states. 0 returns closed cases. A positive value returns that exact case state. |
| created_from | string or null | Inclusive UTC creation-date lower bound. |
| created_to | string or null | Inclusive UTC creation-date upper bound. |
| modified_from | string or null | Inclusive UTC modified-date lower bound. |
| modified_to | string or null | Inclusive UTC modified-date upper bound. |
| owners | string or null | Comma-separated owner IDs. |
| queues | string or null | Comma-separated queue IDs. |
| divisions | string or null | Comma-separated division IDs. Existing role and division authorization still applies. |
| issues | string or null | Comma-separated selected issue IDs. |
| tags | string or null | Comma-separated case tags. |
| include_trashed | boolean or null | Omitted, null, or true preserves the established behavior and includes authorized trashed cases. false excludes cases in the Trash queue. |
| page_number | integer or null | Zero-based page number. Omitted or 0 returns the first page. |
| page_size | integer or null | Number of cases per page. The default is 1000. |
If modified_from or modified_to is omitted from the JSON body, it may instead be supplied as a URL query parameter:
Body values take precedence over URL values.
For page sizes up to 100, results use the established creation-descending order. Larger pages retain the established internal case-ID order.
Response
A successful request returns a bare JSON array. Each item is the lightweight list representation of a case.
The response includes:
- Standard or custom case prefix and ID.
- Division, status, owner, queue, support level, priority, selected issue, root issue category, outcome, asset, company, and primary contact metadata.
- Subject, summary, tags, CSAT/NPS metadata, forum metadata, trash state, last-activity metadata, and primary/secondary contacts.
- UTC created, modified, SLA-target, and closed timestamps with their derived Unix and readable values.
- The legacy property name csr_recieved is retained for backward compatibility.
- CSAT scale metadata (csat_scale_id, csat_display_value, and csat_band) is conditional and may be omitted when it does not apply.
- closed_on is the case's resolved/closed date and time.
- issue_id and issue identify the selected issue. issue_category_id and issue_category identify its root parent category.
- is_trashed is true only when the case is currently in the Trash queue.
The fields and activities properties are not populated by this list endpoint. To retrieve custom fields, activities, activity content, and attachments, use Returning a Case.
Null values are retained according to the existing list contract, except conditional CSAT properties, which may be omitted when unavailable.