Migration

The Migration Wizard imports a customer's data from another accounting provider into SpeyBooks.

Supported providers

Provider	File format	Status
FreeAgent	.xlsx (multi-sheet)	Supported, unified upload
Xero	Manual CSV	Planned
QuickBooks	Manual CSV	Planned
Other	Manual CSV	Supported, manual attachment

Authentication

All endpoints require authentication, and every operation is scoped to the caller's organisation.

Migration lifecycle

A migration moves through a fixed set of states:

setup -> files_attached -> preview_ready -> ready_to_execute -> executing -> completed
                                                                          -> abandoned

Status	Meaning
setup	Created, no files attached
files_attached	At least one import linked
preview_ready	All required imports present
ready_to_execute	All gate checks passed
executing	Finalisation in progress
completed	Sealed (terminal)
abandoned	Manually cancelled (terminal)

The status is recomputed from which imports are attached, and advanced when the conditions for the next state are met.

Singleton constraint

Only one active (non-terminal) migration may exist per organisation at a time. A second attempt is refused with a 409.

Identifiers

Migrations are addressed by a mig_ prefixed id (for example mig_1). Linked imports are addressed by a dimp_ prefixed id (for example dimp_42).

Orchestration model

The wizard orchestrates the standalone importers (the contact importer, the opening-balance importer, and the document importer for outstanding invoices and bills). Each importer is confirmed independently through its own route, and its data is written when it is confirmed. The wizard tracks which imports are attached and validates the composed result before sealing.