> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywise.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Search status updates

> Search and filter published case status updates across all mandates.

Use `GET /v1/statusupdates/` when you need a company-wide view of status
updates. The endpoint searches all of your main cases and sub-cases in one
paginated feed. It only returns updates that paywise has published to you.

## Search

Pass `q` to search case-insensitively within the status title and the visible
text of its description. HTML markup and entities in a rich-text description
do not affect matching. The same parameter also matches an event code, but
event-code matching is exact (case-insensitive). Search terms must contain at
least three characters; shorter values return HTTP 400.

```bash theme={null}
curl -H "Authorization: Bearer $API_TOKEN" \
  "https://api.paywise.de/v1/statusupdates/?q=Zwangsvollstreckung"
```

The title, description, and event-code conditions are alternatives. All other
filters are combined with the search term:

| Parameter          | Meaning                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| `mandate`          | Exact UUID of the main case or sub-case that published the update      |
| `reference_number` | Exact current or historical paywise reference number, case-insensitive |
| `legal_stage`      | Legal stage stored on the status update                                |
| `processing_state` | Processing state stored on the status update                           |
| `created_after`    | Inclusive lower ISO 8601 timestamp for the effective status date       |
| `created_before`   | Inclusive upper ISO 8601 timestamp for the effective status date       |

```bash theme={null}
curl -H "Authorization: Bearer $API_TOKEN" \
  "https://api.paywise.de/v1/statusupdates/?q=Zwangsvollstreckung&legal_stage=foreclosure&created_after=2026-08-01T00:00:00Z"
```

`created_after` and `created_before` apply to the business-effective timestamp:
`custom_date` when paywise supplied one, otherwise the database creation
timestamp. The same value is returned as `created`.

## Identify the case

Each result extends the regular status-update payload with two fields:

```json theme={null}
{
  "id": "ff248f9f-98f8-4bad-986f-73a8bf5b2e8a",
  "title": "Zwangsvollstreckung eingeleitet",
  "description": "<p>Wir haben die Zwangsvollstreckung eingeleitet.</p>",
  "legal_stage": "foreclosure",
  "processing_state": "in_progress",
  "created": "2026-08-20T12:00:00Z",
  "downloads": [
    {
      "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "filename": "vollstreckungsnachweis.pdf",
      "mime_type": "application/pdf",
      "download_url": "https://api.paywise.de/v1/mandates/c3b9bdb9-6fc7-48fb-b27d-470ca944f9c0/statusupdates/ff248f9f-98f8-4bad-986f-73a8bf5b2e8a/download/a1b2c3d4-e5f6-7890-1234-567890abcdef/"
    }
  ],
  "mandate": "c3b9bdb9-6fc7-48fb-b27d-470ca944f9c0",
  "reference_number": "K26-3014A"
}
```

`mandate` is always the UUID of the case that published the update. For a
sub-case, this is the sub-case UUID. `reference_number` always contains the
current reference of the main case because sub-cases do not have their own
current paywise reference number. Together, the fields identify both the
source row and its case constellation.

Attachment links in `downloads` remain authenticated API URLs under the
publishing mandate, for example:

```text theme={null}
/v1/mandates/{mandate}/statusupdates/{status}/download/{file}/
```

Collection attachment entries do not include `file_size`. The upload record
does not persist a byte size, and resolving it would require a synchronous
object-storage metadata request for every attachment. The existing
mandate-specific status-update endpoint keeps its current attachment payload.

## Pagination and ordering

The endpoint uses the standard v1 `limit` and `offset` parameters and returns
at most 200 updates per page. Results are newest first by the effective
timestamp described above. Updates with the same timestamp have a stable
secondary order, so repeating the same paginated request does not move a row
between pages.