> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Cases

> Manual review queue, case lifecycle, and dual-review workflows.

A **review case** is created when a verification workflow routes to
`needs_review`. Cases provide a structured review queue where your team can
examine extracted data, documents, check results, and fraud signals before
making a final decision.

## Case lifecycle

```
open → in_review → approved
                 → rejected
                 → escalated → pending_second_review → approved
                                                     → rejected
```

### Statuses

| Status                  | Description                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `open`                  | Unassigned. Waiting in the queue for a reviewer to claim.                                 |
| `in_review`             | Claimed by a reviewer. The reviewer has 30 minutes to act before the claim auto-releases. |
| `escalated`             | Escalated to a senior reviewer or manager.                                                |
| `pending_second_review` | First reviewer submitted a recommendation. Waiting for a second reviewer (dual-review).   |
| `approved`              | Final decision: approved.                                                                 |
| `rejected`              | Final decision: rejected.                                                                 |

**Active statuses:** `open`, `in_review`, `escalated`, `pending_second_review`

**Final statuses:** `approved`, `rejected`

## SLA tracking

Cases track time from when they enter the review queue:

| SLA    | Time in queue      | Urgency              |
| ------ | ------------------ | -------------------- |
| Green  | Less than 4 hours  | On track             |
| Yellow | Less than 24 hours | Approaching deadline |
| Red    | 24 hours or more   | Overdue              |

## Claiming and reviewing cases

### Claim the next case

Atomically claim the next unassigned case from the queue (FIFO):

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/next \
  -H "X-API-Key: vk_live_your_key_here"
```

Returns the full case with session data, documents, and check results. If no
cases are available, returns `204 No Content`.

### Claim a specific case

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/claim \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123"
  }'
```

### Release a claim

If you can't complete the review, release the case back to the queue:

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/release \
  -H "X-API-Key: vk_live_your_key_here"
```

Claims auto-expire after 30 minutes of inactivity.

## Making decisions

### Approve

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/approve \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123",
    "notes": "ID appears genuine. Face match is strong."
  }'
```

### Reject

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/reject \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123",
    "rejection_reason": "Document appears altered.",
    "notes": "Font inconsistency detected on name field."
  }'
```

### Escalate

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/escalate \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_id": "orguser_abc123",
    "reason": "Potential sanctions match requires compliance review.",
    "escalated_to": "usr_compliance_lead"
  }'
```

## Dual-review workflows

For high-risk decisions, you can require two independent reviews. When dual
review is enabled:

1. First reviewer claims and submits a recommendation (approve or reject)
2. Case moves to `pending_second_review`
3. A different reviewer claims and makes the final decision
4. The system enforces that the second reviewer is different from the first

## Listing cases

```bash
curl "https://api.withverifa.com/api/v1/cases?status=open&limit=25" \
  -H "X-API-Key: vk_live_your_key_here"
```

### Queue tab counts

Get badge counts for each queue tab:

```bash
curl https://api.withverifa.com/api/v1/cases/tab-counts \
  -H "X-API-Key: vk_live_your_key_here"
```

```json
{
  "open": 12,
  "in_review": 3,
  "escalated": 1,
  "pending_second_review": 2,
  "approved": 456,
  "rejected": 89
}
```

## Case notes

Add notes to a case for context and collaboration:

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/notes \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Checked against internal records — name matches."
  }'
```

List notes:

```bash
curl https://api.withverifa.com/api/v1/cases/case_abc123/notes \
  -H "X-API-Key: vk_live_your_key_here"
```

## Check overrides

Override a failed check within a case (e.g., approve despite a borderline face
match):

```bash
curl -X POST https://api.withverifa.com/api/v1/cases/case_abc123/override/face_match \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Manual photo comparison confirms identity."
  }'
```

Overrides are recorded in the audit log with the reviewer's identity and reason.

## PII correction

Correct extracted PII during review (e.g., OCR misread a character):

```bash
curl -X PUT https://api.withverifa.com/api/v1/cases/case_abc123/result/pii \
  -H "X-API-Key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "O'\''Brien"
  }'
```

Corrected PII is re-encrypted and the change is audit-logged.

## Webhooks

| Event           | When                                    |
| --------------- | --------------------------------------- |
| `case.created`  | A new review case was created.          |
| `case.claimed`  | A reviewer claimed the case.            |
| `case.approved` | The case was approved (final decision). |
| `case.rejected` | The case was rejected (final decision). |

## Related

* [Sessions](/core-concepts/sessions) — How sessions trigger case creation
* [Workflows](/core-concepts/workflows) — Configure which conditions route to review
* [Identities](/core-concepts/identities) — How case decisions update identity records