---
title: "List the cases of the key's organization and mode, optionally only those one person opened (`openedBy`)"
method: GET
path: "/v1/cases"
---

# List the cases of the key's organization and mode, optionally only those one person opened (\`openedBy\`)

`GET /v1/cases`

## Request

- Base URL: `https://api.evictionsapi.com`
- URL: `https://api.evictionsapi.com/v1/cases`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Query parameters

- `cursor` string
- `limit` string
- `openedBy` string

## Response `200`

A page of cases, newest first.

- object
  - `items` Case[], required
    - `id` string, required
    - `mode` 'test' | 'live', required
    - `state` string, required: Position in the case lifecycle, for example `notice_review` or `filing_submitted`.
    - `heldFrom` string, nullable
    - `openedBy` union: Who opened the case: the person (`id`, and their current display name, `null` when they have none), `{ "kind": "api_key" }` when it was opened with an API key, or `null` when that is not known (a case from before this was recorded).
      - object
        - `id` string, required
        - `name` string, nullable, required
      - object
        - `kind` 'api_key', required
    - `ground` string, required
    - `entryPoint` 'notice' | 'filing', required
    - `courtCaseNumber` string, nullable
    - `court` string, nullable: The court the case goes to, in words, where the rules for its place say which, with the county: for example "Magistrate court of Henry County". `null` where no rule pack covers the place, and for an erased case.
    - `packVersions` object, nullable
    - `data` object, required
    - `deadlines` object[], required
      - `name` string, required
      - `date` string, date, required
      - `citation` string, required
    - `documents` Document[], required
      - `id` string, required
      - `kind` 'evidence' | 'notice' | 'filing' | 'proof' | 'other', required
      - `specId` string, nullable
      - `purpose` unknown
      - `filename` string, required
      - `contentType` 'application/pdf' | 'image/jpeg' | 'image/png' | 'text/plain': Decided from the file's first bytes when it was stored, never from its name. `text/plain` only for a `correspondence` document that is plain text (the body of a forwarded email).
      - `contentHash` string, required: SHA-256 of the document bytes. An attorney approval names these.
      - `createdAt` string, date-time
    - `nextAction` object, required
      - `by` 'customer' | 'attorney' | 'platform' | 'court' | 'none', required
      - `description` string, required
    - `handling` 'automated' | 'attorney_direct' | 'agent_filed': Who does the legal work. `attorney_direct`: a licensed attorney engaged for the case reviews it, serves the notice and files in court, and the platform records each step; it is what a live case is unless the full-service path is open for its property. `automated`: the built-in test pipeline of a test case. `agent_filed`, the full-service path, as we describe it to the owner: We act as your authorized agent. No attorney reviews the case. We are not a law firm and do not give legal advice. Full service is available only in test mode for now; a case is created with it only when `POST /v1/cases` asks for `service: "full"` and that path is open for the property, and it needs the owner's signed authorization (`/v1/cases/{id}/authorization`).
    - `attorney` object, nullable: The attorney engaged for an attorney-direct case, once recorded. Null until then, and always null for a test case.
      - `name` string, nullable, required
      - `firm` string, required
      - `state` string, required: The property's state.
      - `barNumber` string, nullable, required: The attorney's bar number in that state.
    - `erased` boolean: Whether the details of the case were erased, which we do case by case on request. An erased case keeps its id, state, dates, deadline names and charges. In `data` the names and the address read `[erased]` (the state and county are kept) and every other fact is gone; `courtCaseNumber` is null; each document keeps its id and `contentHash`, its `filename` reads `[erased]` and downloading it answers 410 `erased`; messages read `[erased]`. Any request that would change the case answers 409 `erased`.
    - `erasedAt` string, date-time, nullable: When the details were erased. Null for a case that was not erased.
    - `sources` object: Where each answer came from, by field path (`property.line1`, `lease.monthlyRentCents`, `parties.0`, `ledger`): the kind of source, and for a file read the id of the case document it was read from. An answer with no entry was typed. Empty when no answer came from a source. Never holds a value. Send `sources` with `POST /v1/cases` or `PATCH /v1/cases/{id}` to set it (a patch replaces the whole map); a patch that changes an answer without sending `sources` removes that answer's entry.
    - `agent` unknown
    - `authorization` object: Whether your authorization for us to act as your agent is signed, and whether the facts changed after it was signed (then nothing more is done until you sign again).
      - `signed` boolean, required
      - `stale` boolean, required
    - `complaintSignature` object: Whether the court requires the owner to sign the complaint, and whether the current complaint is signed. While it is required and unsigned, the case waits in `filing_approved`. `sworn` (true when present): the filing is an affidavit your named person swears under oath by electronic verification in the app. `signer`: the member the case names to sign it, by user id and the name the filing prints; only that person can sign.
      - `required` boolean, required
      - `signed` boolean, required
      - `sworn` unknown
      - `signer` object
        - `userId` string, required
        - `name` string, required
    - `paymentMethodId` string, nullable: The organization's saved card (`GET /v1/payment-methods`) this case's costs are charged to, or null for the default card. Choose it with `PATCH /v1/cases/{id}`. A chosen card that is removed or declined is not charged: the default card is used instead.
    - `tasks` Task[]: Each outward step of the case, oldest first (as `GET /v1/cases/{id}/tasks`).
      - `kind` 'notice_delivery' | 'filing' | 'summons_order' | 'hearing_appearance' | 'client_signature' | 'court_mail', required
      - `status` 'pending' | 'in_progress' | 'done' | 'failed' | 'cancelled', required
      - `dueAt` string, date-time, nullable, required: When the step must be done by, when there is a deadline.
      - `completedAt` string, date-time, nullable, required
    - `checking` object: Present while we check what the next step sends before it is sent (we check every notice, filing and summons for now): `notice` (the notice to the tenant), `filing` (the court filing) or `summons`. Nothing is sent, and nothing is charged for that step, until it is checked.
      - `stage` 'notice' | 'filing' | 'summons', required
      - `since` string, date-time, required
    - `sentBack` object: Present while the case is on hold because we checked a step before sending it and sent the case back to you: nothing was sent. `note` says why; reply by email, or withdraw the case.
      - `stage` 'notice' | 'filing' | 'summons', required
      - `note` string, required
      - `at` string, date-time, required
    - `claim` object: What the complaint asks the court for besides possession: unpaid rent, where the court lets us claim it as your agent, up to the court's limit where it has one.
      - `claimRent` boolean, required
      - `amountClaimedCents` integer, required: US cents. Zero when no rent is claimed.
    - `hearing` object: The hearing, once the court has set one (or moved it): where the court requires the owner to attend in person (`clientAttends`), you must attend it yourself.
      - `date` string, date, required
      - `time` string, nullable, required: The court's local time, HH:MM, when known.
      - `place` string, nullable, required: Where the court sits for the hearing, when known.
      - `court` string, nullable, required
      - `clientAttends` boolean, required
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `nextCursor` string, nullable, required

## Other responses

- `400`: The request is invalid.
- `401`: The credential is missing or invalid.
- `403`: The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person's role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).
- `404`: Not found.
- `409`: The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.
- `422`: The case did not pass a check.

---

[API](https://skmtc.dev/evictionsapi/apis/evictions-api.md) · [All operations](https://skmtc.dev/evictionsapi/apis/evictions-api/llms.txt) · [OpenAPI document](https://skmtc.dev/evictionsapi/apis/evictions-api/revisions/28459213a1a3?raw)