list_documents
List documents of a specific type from Holded with filters for date range, contact, payment status, and approval status. Supports pagination and field selection to reduce response size.
Instructions
List all documents of a specific type with optional filters for date range, contact, payment status, approval, and sorting. Supports field filtering to reduce response size. NOTE: a document carries three INDEPENDENT and sometimes-conflicting flags — (1) the stored Paid/Pending badge status (set when the document is imported, NOT recomputed), (2) the real outstanding amount paymentsPending (the authoritative math), and (3) approval (filter with approved). A document can be badge-Paid, math-unpaid, and not-approved all at once, so check the flag you actually mean.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination (optional) | |
| paid | No | Filter by payment status: 0=not paid, 1=paid, 2=partially paid | |
| sort | No | Sort order by creation date | |
| limit | No | Maximum number of items to return (default: 50, max: 500) | |
| billed | No | Filter by billed status: 0=not billed, 1=billed | |
| endtmp | No | Ending timestamp (Unix timestamp) for filtering documents by date | |
| fields | No | Select specific fields to return (e.g., ["id", "contactName", "total"]). Reduces response size by 70-90%. If not provided, returns default fields: id, contact, contactName, date, tax, total, status, paymentsPending | |
| docType | Yes | Type of document to list | |
| summary | No | Return only count and pagination metadata without items (default: false) | |
| approved | No | Filter by approval state: 0=not approved, 1=approved. Maps to Holded `filter=approved-<n>`. Independent of the Paid/Pending badge and of paymentsPending. | |
| starttmp | No | Starting timestamp (Unix timestamp) for filtering documents by date | |
| contactid | No | Filter documents by contact ID |