beel_list_invoices
Read-onlyIdempotent
Retrieve a paginated list of a company's invoices, filterable by status, type, series, customer, issue date range, totals, and free text. Get a focused view of the documents you need.
Instructions
Returns a paginated list of the invoices of this company, filterable by status, type, series, customer, date range and free text. Only the documents of the company in the path are returned.
Endpoint: GET /v1/companies/{company_id}/invoices
⚠️ Fiscal guardrails — read before calling:
When an invoice can still be changed, and what to do once it cannot. (resource: beel://guardrails/invoice-state-machine)
For the exhaustive rules and worked examples, call beel_docs_search.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting at 1. The response echoes it back as `pagination.current_page`. | |
| type | No | Filter by invoice type | |
| limit | No | How many items to return per page. The response echoes it back as `pagination.items_per_page`. | |
| search | No | Global search across invoice number, recipient name, recipient NIF, and series code (partial, case-insensitive) | |
| status | No | Filter by invoice status. Accepts a comma-separated list to match any of several statuses, for example `status=DRAFT,ISSUED`. A single value is also valid. | |
| date_to | No | Issue date to (YYYY-MM-DD) | |
| sort_by | No | Field to sort by (e.g., issue_date, invoice_number, invoice_total) | |
| metadata | No | Filter by metadata key/value pairs (exact match, AND between keys). Repeat the bracket-style param to filter on multiple keys. Max 50 pairs per request. Keys must match `^[A-Za-z0-9_\-.]{1,64}$`. Example: `?metadata[external_order_id]=ORD-42&metadata[tenant]=acme` | |
| date_from | No | Issue date from (YYYY-MM-DD) | |
| total_max | No | Maximum invoice total | |
| total_min | No | Minimum invoice total | |
| company_id | Yes | Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed. | |
| sort_order | No | Sort direction | desc |
| customer_id | No | Filter by customer UUID | |
| fiscal_only | No | When `true`, returns only fiscal documents (STANDARD, CORRECTIVE, SIMPLIFIED), excluding proformas and any other non-fiscal document. Defaults to `false` (the list returns every document type). Ignored when an explicit `type` is given. | |
| series_code | No | Filter by series code (exact match, case-insensitive). Use `search` for partial matching across the invoice number, recipient and series code. | |
| external_ref | No | Filter by exact external reference (client-supplied order/cart/contract id). | |
| recipient_nif | No | Filter by recipient's NIF (partial search) | |
| invoice_number | No | Search by invoice number (e.g., 2025/0001) | |
| recipient_name | No | Filter by recipient's fiscal name (partial, case-insensitive search) | |
| taxable_base_max | No | Maximum taxable base | |
| taxable_base_min | No | Minimum taxable base | |
| verifactu_status | No | Filter by the VeriFactu submission status of the invoice, using the very same vocabulary that `verifactu.submission_status` publishes on each invoice. `NOT_SUBMITTED` selects issued invoices with VeriFactu enabled whose registration never happened (no live record). | |
| verifactu_enabled | No | Filter by whether VeriFactu is enabled for the invoice — the same flag published as `verifactu.enabled`. `false` returns the invoices that never reach AEAT. | |
| rectified_invoice_id | No | Return the corrective invoices that correct this invoice. Accepts the id of an issued invoice; a single invoice can have several partial correctives. |