Listing filters

The List invoices (GET /invoices) and List credit notes (GET /credit-notes) endpoints return a paged set of documents. You filter them with a single query parameter — q. The same syntax works on both.

Filtering with `q`

Filter a field with field:value, combine conditions with AND, and use [start TO end] for ranges. Direction (AP/AR) is just another field — type:Sent or type:Received:

GET /invoices?q=status:success
GET /invoices?q=type:Received
GET /invoices?q=total.amount:[100 TO 500]
GET /invoices?q=issued:[2024-01-01T00:00:00.000Z TO 2024-01-31T23:59:59.999Z]
GET /invoices?q=status:success AND total.currency:EUR

🚧
Always join multiple conditions with AND — without it, terms are treated as OR and widen the results. Wrap values containing a space in quotes, e.g. status:"pending submission". Dates use ISO 8601 in UTC.

Results are paged with limit (default 5, max 500) and skip (default 0). The response returns the total match count and the current page — { "total": 128, "items": [ … ] } — so increase skip by limit each request until you've read all total matches.

See Supported filter fields at the bottom of this page for everything you can filter on.

Common filters

By status — only successful, or only failed:

GET /invoices?q=status:success
GET /invoices?q=status:error

By direction (AP / AR) — received documents are your accounts payable (AP); sent are accounts receivable (AR):

GET /invoices?q=type:Received
GET /credit-notes?q=type:Sent

Poll for newly updated documents — the modified field changes whenever a document does (e.g. a submission succeeds or fails). Combine a modified window with a status filter and move the window forward each run. Daily and hourly examples:

# Daily — succeeded yesterday
GET /invoices?q=modified:[2024-06-01T00:00:00.000Z TO 2024-06-01T23:59:59.999Z] AND status:success&limit=500

# Hourly — succeeded in the last hour
GET /invoices?q=modified:[2024-06-01T09:00:00.000Z TO 2024-06-01T09:59:59.999Z] AND status:success

# Hourly — failed in the last hour
GET /invoices?q=modified:[2024-06-01T09:00:00.000Z TO 2024-06-01T09:59:59.999Z] AND status:error

Received (AP) in the last hour — combine type:Received with a modified window in the same q (works the same on /credit-notes):

GET /invoices?q=type:Received AND modified:[2024-06-01T09:00:00.000Z TO 2024-06-01T09:59:59.999Z]

Add AND status:success or AND status:error to narrow to a particular state.

Supported filter fields

The fields you can filter on with q (field:value), by resource. Invoices and credit notes share the same document fields; organisations are listed via the Enterprise API GET /organisations.

Field	Invoices	Credit notes	Organisations	Description
`id`	✓	✓	✓	Unique document or organisation ID.
`status`	✓	✓	✓	Documents: `success`, `error`, `"pending submission"`. Organisations: e.g. `active`.
`type`	✓	✓	—	Direction: `Sent` (AR) or `Received` (AP).
`ref`	✓	✓	—	Document number / reference.
`issued`	✓	✓	—	Issue date. Supports ranges.
`modified`	✓	✓	—	Last-updated timestamp. Supports ranges.
`created`	✓	✓	—	Created timestamp. Supports ranges.
`total.amount`	✓	✓	—	Total amount. Supports ranges.
`total.currency`	✓	✓	—	Three-letter currency code.
`recipient.name`	✓	✓	—	Recipient (customer) name.
`recipient.address.country`	✓	✓	—	Recipient country (ISO 3166-1 alpha-3).
`sender.name`	✓	✓	—	Sender (supplier) name; present on received (AP) documents.
`taxId`	✓	✓	✓	Tax identification number.
`country`	✓	✓	✓	Country code.
`route`	✓	✓	—	Route used to send / receive the document.
`routeRef`	✓	✓	—	Reference returned by the route.
`error.name`, `error.message`	✓	✓	—	Error detail on failed documents.
`invoiceRefs`	—	✓	—	Invoice reference(s) the credit note applies to.
`name`	—	—	✓	Organisation name.
`plan`	—	—	✓	Subscription plan, e.g. `"Enterprise Plus"`.
`defaultRoute`	—	—	✓	Organisation's default route.
`routes`	—	—	✓	Routes enabled for the organisation.
`onboarded`	—	—	✓	Whether onboarding is complete (`true` / `false`).
`customInfo.peppolId`	—	—	✓	Registered PEPPOL identifier.

ℹ️
Organisation listing is an Enterprise API endpoint (enterprise key required) and defaults limit to 20.

Filtering with q

Common filters

Supported filter fields

Filtering with `q`