List documents
list_documentsList the business's documents — invoices, quotes, credit notes, recurring invoices, bills, purchase orders, debit notes and goods received notes. This is the complete, authoritative document surface: it reads both document stores. Rows are paginated (50 per page, 200 max), so a count or total is only safe when taken from meta.total or from every page — never by summing one page's rows while meta.truncated is true. Rows come newest first. Optionally filter by type (invoice, quote, bill, …), direction (in/out), status (e.g. overdue, due, paid, partiallypaid), a query substring (reference/number, name, notes — jump straight to one document by its reference), currency (ISO 4217, e.g. USD), a due-date range (from/to), unpaid (only rows with an outstanding balance), min_outstanding (minimum outstanding amount) and/or repeating (only live repeat series) — combine e.g. type=bill + unpaid + status=overdue to pull only overdue bills in one call, or type=invoice + query= to fetch a specific invoice. To find what repeats, or before stopping a repeat, use repeating=true (with contact for one customer): type=recurring is a document type, not whether a series is running. Each row carries totals, outstanding, status, type, type_label and contact. Use get_document for one document's full detail.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Only documents with a due date on/before this date (inclusive, ISO 8601; e.g. today to isolate bills due by now). Documents with no due date are kept. | |
| from | No | Only documents with a due date on/after this date (inclusive, ISO 8601, e.g. "2026-01-01"). Documents with no due date are kept. | |
| type | No | The kind of document. One of: invoice — Bill a customer for goods or services. Money in.; quote — A pre-sale estimate for a customer; becomes money in once accepted.; recurring — An invoice that repeats on a schedule. Money in.; debit_note — Reduce what you owe a supplier (offsets a bill). Money in.; credit_note — Refund or reduce a customer's invoice. Money out.; purchase_order — Order goods or services from a supplier. Money out.; bill — A supplier's bill that you owe. Money out.; grn — Record stock received against a purchase order. Money out.. | |
| limit | No | Max rows to return in this page (default 50). Responses include next_cursor / truncated / total; pass next_cursor back as `cursor` to fetch the next page. Never silently truncated. | |
| query | No | Case-insensitive substring match over the document's text (reference/number, name, notes, purchase order, contact and line items). Combine with type to jump straight to one document by its reference number, e.g. type=bill, query="4B66E86E-0286". | |
| cursor | No | Opaque pagination cursor. Omit for the first page; pass the next_cursor from a previous response verbatim to fetch the next page. | |
| status | No | Filter to documents whose computed status matches (case-insensitive), e.g. "overdue", "due", "paid", "partiallypaid", "sent", "draft". Combine with type=bill for overdue-bill analysis. | |
| unpaid | No | When true, return only documents with an outstanding balance (excludes fully paid / zero-outstanding rows). | |
| contact | No | Filter to documents for this contact id (a client or supplier). | |
| currency | No | Filter to documents in this currency (ISO 4217 code, e.g. "USD", "ZAR"). Documents with no stored currency are excluded when set. | |
| direction | No | Money direction filter: "in" for sales documents (invoices, quotes, debit notes), "out" for purchase documents (bills, POs, credit notes, GRNs). | |
| repeating | No | When true, return only the documents whose repeat schedule is on: each live series' template. Generated copies and stopped series are left out. Pass a row's id to set_recurring_invoice to stop or change that series. | |
| min_outstanding | No | Only documents whose outstanding balance is at least this amount (inclusive). |