# Step 2: Create and manage cases

A case is the container for everything else. Extraction codes and exports always belong to a case.

> warn
> Creating a case and starting an export need an **active plan** on your organization. Without one, those calls are refused with 403. If you see this on a new organization, contact Hearsay; do not retry.

## Create a case

`POST /case`

- Required: `name`. `dueDate` is optional.
- Common optional fields: `description`, `matterId` (your own client or matter reference; it is printed on invoices), `priority` (`low`, `medium`, `high`, `urgent`), `status` (`open`, `closed`, `archived`, `pending`), `tags` and `metadata`.
- The caller becomes the case owner.
- The response wraps the case with its members and counts. Save the case id from `data.case.id`; every later step needs it.
- **Optional shortcut:** the same call can create the first extraction code. Set `createExtractionCode` to true and fill in the custodian fields (`custodianName`, `custodianEmail`, `custodianPhone`, `requestedSources`, `sendEmail`). For a clear, auditable flow, we recommend creating the case first and the code separately (Step 3).

## Update a case

`PATCH /case/{caseId}`

- You can change `name`, `description`, `matterId`, `status`, `priority`, `metadata` and `tags`.
- Send only the fields you want to change.
- Renaming a case also changes its slug. Always refer to cases by `id`, never by name or slug.

## List and read cases

- `GET /case` lists the cases the user can see in the organization from the header, most recently updated first. Filters include `searchText`, `status`, `priority`, `tags` and `isArchived`. Each row holds the case under `case`, so a case id is at `data.data[].case.id`. Page through the results as described in "Rules for every call".
- The list can include cases another firm shared with you. Check that a case belongs to the work you were given before you act on it.
- `GET /case/{caseId}` returns one case with its members, pending invitations, active extraction codes and conversation count.


## Example
Create a case:

```sh
curl -X POST "https://api.usehearsay.com/case" \
  -H "Authorization: Bearer $TOKEN" \
  -H "organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Doe v. Example Corp",
    "dueDate": "2026-11-30T00:00:00.000Z",
    "matterId": "MAT-0042",
    "priority": "medium"
  }'
```

The case id is `data.case.id`:

```json
{
  "data": {
    "case": {
      "id": "507f1f77bcf86cd799439011",
      "name": "Doe v. Example Corp",
      "slug": "doe-v-example-corp",
      "matterId": "MAT-0042",
      "priority": "medium"
    },
    "usersWithAccess": [],
    "extractionCodes": [],
    "totalExtractionCodes": 0,
    "conversationsCount": 0
  },
  "statusCode": 201,
  "timestamp": "2026-01-15T10:15:00.000Z"
}
```