Create a new migration

POST https://app.speybooks.com/api/v1/migrations/

Start a new migration session. Specifies the source provider and cutover date (the date from which SpeyBooks takes over).

Validation

  • provider must be one of: freeagent, xero, quickbooks, other
  • cutoverDate must be YYYY-MM-DD format
  • Organisation must not have an active (non-terminal) migration
  • Organisation must not use cash VAT scheme (MW-7 gate)

Concurrency

The singleton constraint is checked both by a SELECT and by the partial unique index on migrations. If a concurrent insert wins the race, the unique violation is caught and returned as 409.

Returns 201 with the initial migration in setup status.

Error responses:

  • 400 { code: "validation_error" } — invalid provider or date format
  • 409 { code: "MIGRATION_SINGLETON_VIOLATION" } — active migration already exists
  • 422 { code: "CASH_VAT_NOT_SUPPORTED" } — cash VAT scheme not supported for migration

Body parameters

cutoverDate string required
Cut-over date (YYYY-MM-DD). Transactions before this date are migrated; transactions on/after are entered directly in SpeyBooks.
date
provider string required
Source accounting provider.
freeagentxeroquickbooksother

Response

201 Migration created in setup status. Returns migration ID, provider config, and empty import slots.
Show response fields
balancesImportId string nullable
billsImportId string nullable
contactsImportId string nullable
cutoverDate string
id string
invoicesImportId string nullable
provider string
providerLabel string
status string
warnings array<object>

Error codes

400 Invalid provider or date format.
409 An active migration already exists (singleton violation).
422 Cash VAT scheme not supported for migration.