Upload invoices file

POST https://app.speybooks.com/api/v1/invoice-imports/upload

Upload an outstanding invoices CSV. The ODCE engine parses invoices, resolves contacts via UCI-lite matching (exact normalised name match then Levenshtein fuzzy at ≥ 85%), and validates the clearing zero-sum invariant.

Requires an active opening balance imported in Clearing Mode. Blocked if a completed invoice import already exists (singleton) or if the organisation uses Cash VAT accounting.

Maximum file size: 5 MB. Only CSV files are accepted.

The response includes the full preview payload — rows with per-row contact resolution, clearingProof, and warnings — everything needed to render the import wizard UI. There is no need for a subsequent GET call after upload.

Response

201 CSV parsed, contacts 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
canConfirm boolean
clearingProof object
Show child attributes
cleared boolean
importDelta string
netBalance string
openingBalance string
cutoverDate string
direction string
errors array<object>
filename string
importId string
rows array<object>
Show child attributes
contact object
Show child attributes
confidence integer
contactId string
contactName string
outcome string
reason string
contactName string
docDate string
docNumber string
dueDate string
error string nullable
errorDetail string nullable
gross string
outstanding string
paid string
rowIndex integer
status string
stats object
Show child attributes
errorRows integer
totalGross string
totalOutstanding string
totalPaid string
totalRows integer
validRows integer
warnings array<object>

Error codes

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