Skip to main content
GET
List all cases
Retrieve a list of cases, newest first.

Permission

You see the cases you created, or every case in your organisation if you have organisation_cases:read or your organisation has shared cases enabled. An API key without organisation_cases:read receives an empty list, unless your organisation has shared cases enabled. See Permissions and API Keys. Pass scope=own to see only the cases you created, or scope=org to ask for every case in the organisation. If you cannot see every case, scope=org returns 400 with request.cases.case.org-scope-not-permitted.

Finding a case by label

Pass the optional label query parameter to fetch the case (or cases) whose label matches exactly. The match is case-sensitive and covers the same cases as the unfiltered list.
A typical integration uses this to check whether a case already exists for an external reference before creating a new one, making the create-or-fetch flow safely idempotent.

Best Practices

  1. Use List for Overview: Use GET /cases for dashboards and case selection.
  2. Use Details for Specifics: Use GET /cases/{id} when you need file-level information.
  3. Use Label Lookup for Idempotency: Use GET /cases?label=... when you have an external reference (claim number, policy ID) and want to find or create a case by that identifier without paginating.
  4. Use Search for Discovery: For partial or fuzzy matching across case labels and file names, use GET /search instead. ?label= on this endpoint is exact-match only.
  5. Monitor Status: Check file_analysis_status for processing updates.

Authorizations

x-api-key
string
header
required

Query Parameters

limit
integer
default:20

Maximum number of cases to return

Required range: 1 <= x <= 100
offset
integer
default:0

Number of cases to skip for pagination

Required range: 0 <= x <= 9007199254740991
label
string
Required string length: 1 - 255
scope
enum<string>

Explicitly request a visibility scope. "own" forces the result to only cases the caller created, even if they can view the whole organisation. "org" explicitly requests every case in the organisation — rejected with 400 if the caller cannot view org-wide. Omitted (default): today's behaviour is unchanged — the caller's resolved org-wide visibility decides the result set, with no rejection.

Available options:
own,
org

Response

List of cases retrieved successfully

cases
object[]
required
total
integer
required
Required range: 0 <= x <= 9007199254740991
limit
integer
required
Required range: x <= 9007199254740991
offset
integer
required
Required range: 0 <= x <= 9007199254740991