Upload opening balances

POSThttps://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, so there is no need for a subsequent GET call after upload.

Response

201CSV parsed, accounts auto-mapped, preview generated. Returns full mapping wizard payload: mappings, lines, balance proof, unmapped accounts, and canConfirm gate.
Show response fields
balanceProofobject
Show child attributes
balancedboolean
deltastring
roundingAmountstring
roundingInjectedboolean
totalCreditstring
totalDebitstring
canConfirmboolean
cutoverDatestring
errorsarray<object>
filenamestring
importIdstring
linesarray<object>
Show child attributes
accountCodestring
accountIdstring
accountNamestring
accountTypestring
creditstring
debitstring
isRoundingboolean
sourceLabelstring
mappingsarray<object>
Show child attributes
confidenceinteger
methodstring
sourceLabelstring
targetAccountIdstring
targetCodestring
targetNamestring
targetTypestring
openingBalanceModestring
statsobject
Show child attributes
errorRowsinteger
ignoredRowsinteger
totalRowsinteger
validRowsinteger
unmappedarray<object>

Error codes

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