Approve bill
Approve a bill. Only bills in NeedsApproval state.
Authentication. An API key (x-dolfin-api-key) together with the x-dolfin-organisation-id header identifying the organisation, or a JWT Bearer token that carries the organisation in its claims.
Authorizations
An API key issued to your client. It carries the client's scope; org-scoped calls also require the x-dolfin-organisation-id header. Keys are created and revoked by a client administrator.
Headers
Target organisation. Required when authenticating with an API key; omit for Bearer callers (resolved from the token).
Path Parameters
Response
OK
Created, Extracting, PendingReview, NeedsApproval, Approved, Rejected, Scheduled, Paid, ExtractionFailed, PaymentInProgress, PaymentFailed, Voided, OcrProcessing, OcrFailed Upload, Email, Webhook Suggested supplier match. Auto-accepted as the Supplier on review submit if Supplier is not set. Found in tiers: exact tax id / email, then exact name, then a fuzzy weighted name + delivery-address match.
Confidence (0-1) of SuggestedMatchedSupplierId: 1.0 for a tax-id/email hit, ~0.95 for an exact name, and the computed weighted score for a fuzzy hit. Null when there is no suggestion. Use it to grade how the suggestion is surfaced (e.g. ask for confirmation below a threshold).
Ship-to / delivery address as printed on the bill, weighed against the supplier's address in fuzzy matching.
The supplier's address as components, extracted from the document. Null when the document's address block could not be broken down.
The delivery address as components, extracted from the document. This is what is matched against an organisation's address when routing a bill received against a company. Null when the document's address block could not be broken down.
ISO 4217 currency code (e.g. GBP, USD, EUR)
Supplier credit netted against this bill.
What's left to pay after supplier credit (TotalAmount − AmountCredited). This is what the payment flow charges.
Extraction confidence (0-1) reported by the extractor. Null until extraction completes.
Set when Voided. A null VoidedBy with a non-null VoidedAt ⇒ policy auto-void.
The earlier bill this one appears to duplicate — same organisation, same supplier, same invoice number. Null when no duplicate was found. While set and not yet confirmed as a false alarm, the bill cannot be approved; confirm it is not a duplicate to clear that, or void it.
When the possible duplicate was detected, which happens automatically just after the bill's document is extracted.
Which evidence matched: SupplierId means both bills resolve to the same supplier record; SupplierName means only their extracted supplier names agree, which is a weaker signal worth checking more carefully.
SupplierId, SupplierName, null When someone confirmed this bill is not a duplicate. Once set, the bill can be approved; duplicateOfBillId is kept so the link to the other bill stays visible.
The approval policy applied at submit-review, if any (UI badge).
Deterministic explanation of the approval decision.
Users this bill was routed to for approval — the pending reviewers while in NeedsApproval.
Three-way match facts for this bill: the match status plus the purchase orders and delivery notes it is matched to. Null means the bill has no match group at all, which is the normal state when there was no candidate purchase order; it does not mean 'unmatched pending'. Only populated when the request asks for it (includeMatch=true) — otherwise it is always null. Fetch the bill's match group for the per-line detail and suggestions behind the summary.
Distinct union of the line items' tags, baked at submit-review — for bill-level filtering.