Find candidate transactions bulk
find_candidate_transactions_bulkBULK / multi-document version of find_candidate_transactions: for MANY outstanding documents at once, return each document alongside its candidate settling bank transactions + best match, in ONE read-only call — so reconciling a large AP/AR backlog needs one call, not one round-trip per bill. Select the document set EITHER by passing an explicit documentids list, OR with the same filters as list_documents (type, direction in/out, contact, status e.g. overdue, from/to due-date range, unpaid, min_outstanding) — e.g. type=bill + unpaid + status=overdue to pull candidates for every overdue bill. Capped at limit documents (default 50, hard max 200); when more match, truncated is true and matched reports the full count, so narrow the filter or page. Returns {results [{document {...}, candidates [transactions], best {transactionid, confidence, reason}}], count, matched, truncated, limit}. READ-ONLY: it suggests matches, never records them (settle bills via settle_bills). To settle an invoice, first check whether the candidate's bank line already has its own income: list_transactions shows it in that line's $incomeids. If it does, settle with save_income, id = that income and accountid = the invoice id. Use record_document_payment only when the line has no income, because it always creates a new income and would count the money twice.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Only documents with a due date on/before this date (inclusive, ISO 8601). Documents with no due date are kept. | |
| from | No | Only documents with a due date on/after this date (inclusive, ISO 8601). Documents with no due date are kept. | |
| type | No | Filter the document set by kind (invoice, bill, …). Ignored when :documentids is given. | |
| limit | No | Max documents to process this call (default 50, hard max 200). If more match, :truncated is true and :matched reports the full count — narrow the filter or page. | |
| status | No | Filter to documents whose computed status matches (case-insensitive), e.g. "overdue", "due", "partiallypaid". | |
| unpaid | No | When true, only documents with an outstanding balance (excludes fully paid rows). Recommended for reconciliation. | |
| contact | No | Filter to documents for this contact id (a client or supplier). | |
| direction | No | Filter by money direction: "in" (invoices, quotes, credit notes) or "out" (bills, purchase orders, debit notes). | |
| documentids | No | Explicit list of document ids (cont-… or inv-…) to fetch candidates for. When given, the filter fields below are ignored. Foreign/missing ids are silently dropped. | |
| min_outstanding | No | Only documents whose outstanding balance is at least this amount (inclusive). |