Upload opening balances

POST https://app.speybooks.com/api/v1/opening-balances/upload

Upload a trial balance CSV. The OBCE engine parses debit/credit columns (dual-column or signed single-column detection), auto-maps accounts using a 5-tier matching strategy, and validates the balance equation.

If the balance equation has a delta ≤ £0.05, a rounding adjustment is automatically injected to account 7999 (Rounding). Deltas > £0.05 block confirmation.

Supports an optional clearingMode form field. When set to clearing, Trade Debtors and Trade Creditors are routed through migration clearing accounts (1198 MC_AR, 2198 MC_AP) to enable outstanding document imports.

Maximum file size: 5 MB. Blocked if an active OB journal already exists (singleton constraint).

The response includes the full preview payload needed to render the mapping wizard UI — there is no need for a subsequent GET call after upload.

Response

201 CSV parsed, accounts auto-mapped, preview generated. Returns full mapping wizard payload: mappings, lines, balance proof, unmapped accounts, and canConfirm gate.
Show response fields
balanceProof object
Show child attributes
balanced boolean
delta string
roundingAmount string
roundingInjected boolean
totalCredit string
totalDebit string
canConfirm boolean
cutoverDate string
errors array<object>
filename string
importId string
lines array<object>
Show child attributes
accountCode string
accountId string
accountName string
accountType string
credit string
debit string
isRounding boolean
sourceLabel string
mappings array<object>
Show child attributes
confidence integer
method string
sourceLabel string
targetAccountId string
targetCode string
targetName string
targetType string
openingBalanceMode string
stats object
Show child attributes
errorRows integer
ignoredRows integer
totalRows integer
validRows integer
unmapped array<object>

Error codes

400 No file uploaded, parse error, or file exceeds 5MB limit.
409 An active opening balance journal already exists (singleton violation).