Create a new migration

POSThttps://app.speybooks.com/api/v1/migration/

Start a new migration session, naming the source provider and the 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
  • the organisation must not already have an active migration
  • the organisation must not be on the cash VAT scheme, which migration does not support

The singleton is enforced even under a concurrent create: if another insert wins the race, the request is answered with a 409 rather than a second active migration.

Returns 201 with the migration in setup status.

Error responses:

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

Body parameters

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

Response

201Migration created in setup status. Returns migration ID, provider config, and empty import slots.
Show response fields
balancesImportIdstringnullable
billsImportIdstringnullable
contactsImportIdstringnullable
cutoverDatestring
idstring
invoicesImportIdstringnullable
providerstring
providerLabelstring
statusstring
warningsarray<object>

Error codes

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