Upload bills file

POSThttps://app.speybooks.com/api/v1/bill-imports/upload

Upload an outstanding-bills CSV. The engine parses the bills, resolves each supplier contact by name (an exact match first, then a close-match fallback), and validates that the payables clearing account nets to zero.

Requires opening balances already imported in Clearing Mode. Blocked if a completed bill import already exists (one per organisation) or if the organisation uses Cash VAT accounting.

Maximum file size: 5 MB. CSV only.

The response carries the full preview payload, the parsed rows with per-row contact resolution, the clearingProof, the stats, and the warnings, everything the import wizard needs to render. No follow-up GET is required after upload.

Error responses:

  • 422 { code: "CASH_VAT_UNSUPPORTED" }: the organisation uses the Cash VAT scheme
  • 422: no opening balances, or opening balances not in Clearing Mode
  • 409: a completed bill import already exists for the organisation
  • 413: the file exceeds 5 MB

Response

201CSV parsed, suppliers resolved, clearing proof validated. Returns full import wizard payload: rows with per-row contact resolution, clearingProof, stats, errors, warnings, and canConfirm gate.
Show response fields
canConfirmboolean
clearingProofobject
Show child attributes
clearedboolean
importDeltastring
netBalancestring
openingBalancestring
cutoverDatestring
directionstring
errorsarray<object>
filenamestring
importIdstring
rowsarray<object>
Show child attributes
contactobject
Show child attributes
confidenceinteger
contactIdstring
contactNamestring
outcomestring
reasonstring
contactNamestring
docDatestring
docNumberstring
dueDatestring
errorstringnullable
errorDetailstringnullable
grossstring
outstandingstring
paidstring
rowIndexinteger
statusstring
statsobject
Show child attributes
errorRowsinteger
totalGrossstring
totalOutstandingstring
totalPaidstring
totalRowsinteger
validRowsinteger
warningsarray<object>

Error codes

400No file uploaded, parse error, empty file, or file exceeds 5MB limit.
409An active bill import already exists (singleton violation).
422Precondition failed: no opening balances, OB not in clearing mode, or Cash VAT scheme.