Execute migration

POSThttps://app.speybooks.com/api/v1/migration/{id}/execute

Finalise a validated migration and seal it. This operation is irreversible.

Execute does not import the data. The standalone imports (contacts, opening balance, invoices, bills) have already been written when they were confirmed in the earlier steps. Execute takes an organisation-level lock to prevent concurrent finalisation, re-runs the gate checks, runs the final balance checks (the clearing accounts net to zero and the ledger conserves), builds the reconciliation proof, and seals the migration as completed with that proof and a completion timestamp. Sealing is terminal.

The migration must be in ready_to_execute; call /validate first.

If the migration is already completed, the existing reconciliation proof is returned without re-sealing, so the call is safe to retry on a network failure.

On a gate or balance failure the migration is returned to ready_to_execute and a 422 is returned with the failing check, so it can be retried once the underlying issue is fixed.

Error responses:

  • 404 { code: "not_found" }: migration not found
  • 422 { code: "INVALID_TRANSITION" }: not in ready_to_execute status
  • 422: a gate or balance check failed (the failing check is in the response)

Path parameters

idstringrequired
Migration ID (e.g. mig_1). Must be in ready_to_execute status.

Response

200Migration executed and sealed. Returns reconciliation proof. Idempotent if already completed.
Show response fields
migrationIdstring
reconciliationobject
Show child attributes
contactsobject
Show child attributes
conflictsinteger
createdinteger
currencystring
cutoverDatestring
ledgerobject
Show child attributes
balancedboolean
obobject
Show child attributes
balancedboolean
modestring
transactionIdstring
statusstring

Error codes

400Invalid migration ID format.
404Migration not found.
422Migration is not in ready_to_execute status, or execution failed validation.