Cases

Understand how the linking graph turns shared field values into cases: automatically created groups of two or more related documents, listed via /v1/cases.

Cases are automatically created groups of two or more documents that are connected through shared transaction or reference entity values. For example, an invoice, a purchase order, and a delivery note sharing the same PO number form a case. Cases provide a high-level view of document relationships without needing to navigate the full graph.

Use this endpoint to retrieve all cases in your workspace for building case lists, dashboards, or review queues. Each case includes a document_count, a stable UUID id used for detail lookups, and a content-derived case_key (a hex hash of the member document set).

The response includes a links.self URL for each case that points to the case detail endpoint. The label field contains an auto-generated human-readable name when available, or null for cases that have not yet been labelled.

Pair this endpoint with Case Graph to visualize individual cases, or with Document-Case Map for a flat document-to-case lookup. Cases are rebuilt automatically during backfill — if you have recently reclassified link keys, trigger a backfill first to ensure case assignments are up to date.

• Each case is keyed on a stable UUID (id) and also carries a deterministic case key (hex hash of its document IDs)
• Cases are created by the linking pipeline during backfill or real-time processing
• Documents linked only through identity entities (e.g. vendor ID) appear as entity groups, not cases

Response

{
  "data": [
    {
      "id": "5c7fa78c-4d92-4613-9f42-9fe74458d8a9",
      "case_key": "a1b2c3d4e5f6a7b8",
      "label": "Acme Corp Q4 Invoices",
      "document_count": 4,
      "created_at": "2024-09-14T10:32:00.000Z",
      "links": {
        "self": "/v1/cases/5c7fa78c-4d92-4613-9f42-9fe74458d8a9"
      }
    }
  ]
}

Errors