---
title: "List entity-scoped candidate documents for a transaction"
method: GET
path: "/companies/{companyId}/transactions/{id}/document-candidates"
tags: ["Transactions"]
---

# List entity-scoped candidate documents for a transaction

`GET /companies/{companyId}/transactions/{id}/document-candidates`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/companies/{companyId}/transactions/{id}/document-candidates`
- Auth: HTTP bearer

The mirror of /documents/{id}/match-candidates (#2013). Search and ranking run on the server; the attach-document picker previously filtered a ten-row client page, so a company holding hundreds of unmatched receipts could be shown none. Candidates are filtered on the DISPLAYED document type, which is re-derived from metadata and can differ from the stored `type` column. A candidate whose `attachedTransactionId` is non-null is already attached to another transaction: attaching it here replaces that link rather than adding one, and for a bill that reverses its payment posting.

## Query parameters

- `query` string
- `limit` integer

## Response `200`

Ranked candidate documents, money-compatible with the transaction

- object
  - `success` boolean
  - `data` object
    - `candidates` TransactionDocumentCandidate[]
      - `document` object
        - `id` string, uuid
        - `name` string
        - `fileName` string
        - `type` 'invoice' | 'bill' | 'receipt' | 'contract' | 'statement': The DISPLAYED type, re-derived from metadata; may differ from the stored column.
        - `status` string
        - `vendorName` string, nullable
        - `customerName` string, nullable
        - `invoiceNumber` string, nullable
        - `amountCents` integer, nullable
        - `currency` string, nullable
        - `minorUnitExponent` integer, nullable
        - `docDate` string, nullable
        - `paymentStatus` string, nullable
      - `attachedTransactionId` string, nullable: The transaction this document is already attached to, or null when it is free. A matched but unpaid bill keeps this while its status stays `reviewed`, so status alone cannot tell the two apart. Attaching a marked candidate REPLACES the existing link.
      - `score` integer
      - `amountDiffCents` integer, nullable
      - `dateDiffDays` integer, nullable
      - `textScore` number

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `404`: Resource not found
- `422`: Request failed validation

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)