Upload provider export

POST https://app.speybooks.com/api/v1/migrations/{id}/upload-provider

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

FreeAgent Flow

  1. Validate file: must be .xlsx, under 10MB
  2. Parse via parseFreeAgentExport() — splits sheets into CSV buffers for contacts, trial balance, invoices, bills
  3. Validate required sheets are present
  4. Determine clearing mode: if invoices or bills exist, opening balance uses clearing account reconciliation
  5. Call uploadContacts() service directly (same transaction, same RLS context)
  6. Call uploadOpeningBalance() service directly
  7. If invoices/bills sheets exist, store as base64 in mapping_data.deferredSheets for later processing
  8. Attach import IDs to the migration
  9. Advance migration status

Deferred Sheets

Invoices and bills are deferred because they depend on the opening balance being confirmed first (clearing account reconciliation). The frontend calls /upload-deferred after OB confirmation.

Request

Multipart file upload — the file field must contain a single .xlsx file.

Error responses:

  • 400 { code: "validation_error" } — not FreeAgent provider, no file, or not .xlsx
  • 400 { code: "parse_error" } — XLSX parsing failed
  • 400 { code: "validation_error" } — required sheets missing
  • 413 — file exceeds 10MB
  • 422 { code: "PROVIDER_PARSE_FAILED" } — required sheets (contacts or balances) failed to import
  • 422 { code: "INVALID_TRANSITION" } — migration is terminal

Path parameters

id string required
Migration ID (e.g. mig_1). Must be FreeAgent provider.

Response

200 File parsed. Returns migration status, per-entity upload results (uploaded/deferred), and matched sheet names.
Show response fields
balancesImportId string
billsImportId string nullable
completedAt string nullable
contactsImportId string
createdAt string date-time
cutoverDate string
id string
invoicesImportId string nullable
provider string
providerLabel string
reconciliation string nullable
sheets array<string>
status string
uploads object
Show child attributes
balances object
Show child attributes
importId string
status string
bills string nullable
contacts object
Show child attributes
importId string
status string
invoices object
Show child attributes
importId string nullable
status string
warnings array<object>

Error codes

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