# List cases

> Returns the prior-authorization cases associated with the authenticated organization.

Source: [https://genhealth.ai/docs/api-reference/v1/cases/list-cases-v2](https://genhealth.ai/docs/api-reference/v1/cases/list-cases-v2)

## Endpoint

`GET /v2/cases`

## Authentication

Send a GenHealth credential in the `Authorization` header:

```http
Authorization: Bearer <YOUR_API_KEY>
Accept: application/json
```

Required scopes: `read:umpa`

## Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | No | Page number. Default: 1. |
| `limit` | query | integer | No | Maximum number of cases to return. Default: 10. |
| `status` | query | string or array<string> | No | Filter by one or more case statuses. |
| `recommendation` | query | string | No | Filter by decision recommendation. |
| `sort_by` | query | string | No | Case field used for sorting. |
| `order_by` | query | string | No | Sort direction. Default: asc. |

## Request examples

### cURL

```curl
curl --request GET \
  --url 'https://api.umpa.genhealth.ai/v2/cases?page=1&limit=10&order_by=asc' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Accept: application/json'
```

### JavaScript

```javascript
const response = await fetch('https://api.umpa.genhealth.ai/v2/cases?page=1&limit=10&order_by=asc', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <YOUR_API_KEY>',
    Accept: 'application/json',
  },
});

const data = await response.json();
```

### Python

```python
import requests

response = requests.get(
    'https://api.umpa.genhealth.ai/v2/cases?page=1&limit=10&order_by=asc',
    headers={
        'Authorization': 'Bearer <YOUR_API_KEY>',
        'Accept': 'application/json',
    },
)

data = response.json()
```

## Responses

| Status | Description |
| --- | --- |
| 200 | A paginated collection of cases. |
| 401 | The bearer token is missing, invalid, or lacks the required scope. |
| 422 | One or more request values failed validation. |

### 200 response example

```json
{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "open",
      "recommendation": "approve",
      "policy_id": "f844ba52-0b67-4874-a06a-900f98b10dd7",
      "created_at": "2026-08-05T14:30:00Z",
      "last_modified": "2026-08-05T14:45:00Z"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 1,
    "totalPages": 1,
    "totalItems": 1,
    "next": 1,
    "previous": 1
  }
}
```

### 401 response example

```json
{
  "detail": "The request could not be completed."
}
```

### 422 response example

```json
{
  "detail": "The request could not be completed."
}
```