Skip to main content
Total invoice spend, overall or per supplier, recipient or month

Authorizations

Authorization
string
header
required

Personal API key sent as a bearer token, together with X-Organization-Id. The key must have at least the access level the endpoint requires (read, write or admin).

Headers

X-Organization-Id
string

The organization to act in. Required for personal API keys; list the organizations you can access with GET /v1/organizations.

Query Parameters

fields
string[]

Return only these fields; use dots for nested fields, such as alert_scope.type. Fields: alert_scope, document_count, total_count, financially_invalid_count, alert_checked_count, alert_checkable_count, organization_currency, currencies, groups, next_cursor.

view_ids
string[]

Invoice number, title, party name or a reference, ignoring case; eight or more digits, or a VAT number with its country prefix, also match an organization or VAT number. Under three characters match the start of the invoice number.

Required string length: 1 - 200
invoice_number
string

Ignoring case; under three characters match its start.

Required string length: 1 - 200
supplier_ids
string[]
company_ids
string<uuid>[]
Required array length: 1 - 1000 elements
without_company
boolean

true: invoices waiting for a person to choose their company (company_id null; setInvoiceCompany); false: those with one. Only members with access to every company see them.

recipient_ids
string[]
categories
enum<string>[]
Available options:
invoice,
credit_note,
self_billed_invoice,
reminder,
collection_notice
currency_codes
string[]
alert_statuses
enum<string>[]

checking: a check is running; has_issues: open alerts; clean: checked, no open alerts; credited: covered by credit notes.

Available options:
not_checked,
checking,
has_issues,
clean,
credited
confidence_levels
enum<string>[]

Extraction confidence.

Available options:
high,
mid,
low,
unknown
check_statuses
enum<string>[]

completed: every matched agreement checked; incomplete: a check missing or failed; not_checkable: credit notes, and invoices fully reversed or without a document.

Available options:
not_checkable,
checking,
not_checked,
completed,
incomplete
has_recorded_match
boolean

Invoices linked to a credit note, and credit notes linked to an invoice.

alert_scope
enum<string>
default:invoice

invoice covers all of the invoice's checks and alerts; selected_agreements covers only the agreements in agreement_ids (required).

Available options:
invoice,
selected_agreements
issued_from
string
Pattern: ^\d{4}-\d{2}-\d{2}$
issued_through
string
Pattern: ^\d{4}-\d{2}-\d{2}$
due_from
string
Pattern: ^\d{4}-\d{2}-\d{2}$
due_through
string
Pattern: ^\d{4}-\d{2}-\d{2}$
created_from
string

Received (created_at) on or after this day, in the organization's time zone.

Pattern: ^\d{4}-\d{2}-\d{2}$
created_through
string

As created_from, on or before.

Pattern: ^\d{4}-\d{2}-\d{2}$
financially_valid
boolean

The amounts add up (amounts.valid).

extraction_confirmed
boolean

A person has confirmed the extracted data.

agreement_ids
string<uuid>[]

Invoices matched to any of these agreements.

has_agreement_match
boolean

Matched to at least one agreement.

has_open_alerts
boolean

Alerts pending or accepted and not credited, even while checking.

deleted
boolean
default:false

true lists only soft-deleted invoices.

stage
enum<string>

Superseded by phase and lifecycle_statuses.

Available options:
inbox,
needs_approval,
on_hold,
approved,
rejected
overdue
boolean
approver
enum<string>

me: invoices where the caller is one of the approvers.

Available options:
me
approver_user_ids
string[]

Approvers include any of these members, by name or through a team, before and after they approve; who must act now is actionable.

Required string length: 1 - 255
phase
enum<string>

As lifecycle.phase.

Available options:
inbox,
approval,
payment,
done
lifecycle_statuses
enum<string>[]

As lifecycle.status.

Available options:
reading,
missing_info,
ready_for_approval,
no_new_charges,
sent_back,
awaiting_approval,
on_hold,
not_ready_to_send,
ready_to_send,
send_failed,
rejected_in_accounting,
sent,
awaiting_payment,
paid,
booked,
closed,
cancelled
actionable
enum<string>

me: invoices whose next action is the caller's (lifecycle.next_action.mine).

Available options:
me
transfer_failures
enum<string>[]

Last send to the accounting system failed with any of these (transfer.failure.code).

Available options:
unsupported_category,
no_connection,
connection_disabled,
invoice_incomplete,
not_coded,
coding_from_other_connection,
amounts_mismatch,
company_mismatch,
supplier_not_in_erp,
supplier_link_unavailable,
supplier_ambiguous,
supplier_same_name,
currency_unsupported,
nothing_to_post,
too_many_lines,
dimension_unsupported,
rounding_account_missing,
sign_in_missing,
sign_in_expired,
sender_permission_missing,
supplier_invoice_flow_off,
duplicate_in_erp,
ambiguous,
changed_after_transfer,
not_supplier_invoice,
registered_differs,
not_bookable,
permission_missing,
credentials_rejected,
rejected,
documents_rejected,
documents_missing,
reply_unreadable,
provider_changed,
unavailable,
transfer_error
transfer_stuck
boolean

Sent to the accounting system, neither booked nor paid there, and rejected in its approval or waiting more than seven days.

join_operator
enum<string>
default:and

search, invoice_number, agreement_ids, created_from, created_through, review_recommended, deleted, stage, overdue, approver, approver_user_ids, phase, lifecycle_statuses, actionable, transfer_failures and transfer_stuck always apply.

Available options:
and,
or
not
enum<string>[]

List filters to invert.

Available options:
supplier_ids,
recipient_ids,
categories,
currency_codes,
confidence_levels,
check_statuses,
alert_statuses,
agreement_ids
group_by
enum<string>

Also return the totals per supplier, recipient or issue month in groups, one page at a time.

Available options:
supplier,
recipient,
month
limit
integer
default:50
Required range: 1 <= x <= 1000
cursor
string
Maximum string length: 4096
sort
enum<string>
default:total_amount_excluding_vat

Group order, with group_by. Totals sort by their organization-currency value. key sorts by the group key, so months in calendar order.

Available options:
total_amount_excluding_vat,
total_amount_including_vat,
invoice_count,
key
direction
enum<string>
default:desc
Available options:
asc,
desc

Response

Invoice counts and totals by currency, and with group_by a page of groups.

alert_scope
object
required
document_count
integer
required

Visible document rows matching this selection, including reminders and collection notices.

total_count
integer
required

Purchase invoice and credit-note count, excluding letter rows.

financially_invalid_count
integer
required
alert_checked_count
integer
required
alert_checkable_count
integer
required
organization_currency
object
required

Totals converted to the organization currency at each invoice's date, rounded to cents. An invoice without an amount or exchange rate adds nothing.

currencies
object[]
required
groups
object[]

With group_by: a page of groups with their invoice counts and spend.

next_cursor
string | null

With group_by: the cursor for the next page of groups; null at the end.