Upload provider export

POSThttps://app.speybooks.com/api/v1/migration/{id}/upload-provider

Upload a provider export file for automated extraction and mapping. Currently this supports FreeAgent .xlsx files only.

For a FreeAgent upload, the file is validated (it must be an .xlsx under the size limit) and parsed into its component sheets (contacts, trial balance, sales invoices, bills). The contacts and the opening balance are imported straight away, in the caller's organisation scope. If the export also carries invoice or bill sheets, those are held for later processing, because they depend on the opening balance being confirmed first (clearing-account reconciliation). The resulting import ids are attached to the migration and its status is advanced.

The deferred invoice and bill sheets are processed by the deferred-sheets endpoint once the opening balance is confirmed.

The request is a multipart upload; the file field must carry a single .xlsx file.

Error responses:

  • 400 { code: "validation_error" }: not a FreeAgent provider, no file, or not .xlsx
  • 400 { code: "parse_error" }: the .xlsx could not be parsed
  • 400 { code: "validation_error" }: a required sheet is missing
  • 413: the file exceeds the size limit
  • 422 { code: "PROVIDER_PARSE_FAILED" }: a required sheet (contacts or balances) failed to import
  • 422 { code: "INVALID_TRANSITION" }: the migration is in a terminal state

Path parameters

idstringrequired
Migration ID (e.g. mig_1). Must be FreeAgent provider.

Response

200File parsed. Returns migration status, per-entity upload results (uploaded/deferred), and matched sheet names.
Show response fields
balancesImportIdstring
billsImportIdstringnullable
completedAtstringnullable
contactsImportIdstring
createdAtstringdate-time
cutoverDatestring
idstring
invoicesImportIdstringnullable
providerstring
providerLabelstring
reconciliationstringnullable
sheetsarray<string>
statusstring
uploadsobject
Show child attributes
balancesobject
Show child attributes
importIdstring
statusstring
billsstringnullable
contactsobject
Show child attributes
importIdstring
statusstring
invoicesobject
Show child attributes
importIdstringnullable
statusstring
warningsarray<object>

Error codes

400Wrong file format, parse error, or missing required sheets.
404Migration not found.
413File exceeds 10MB limit.
422Migration is terminal, or required sheets (contacts/balances) failed to parse.