When to use this endpoint

Connect and configure the provider first. Read Accounting_syncPolicyGet to identify enabled phases. Call again to resume a paused run; do not equate ok:1 with every record being synchronized.

Authentication and permissions

Use signed API-key authentication or a logged-in CRM session on the account’s routed host. API keys act as their owner; session requests require the dispatcher’s CSRF token where configured. Tenant rows and settings belong to that authenticated account.

These handlers add no accounting page or CRM2 role check. The dispatcher has no Accounting/DataSync object-scope mapping. Settings-screen access controls are separate from these shared API handlers; CRM2 screen roles are not a CRM1 API requirement.

Parameters

ParameterTypeRequiredDescription
providerStringYesCase-insensitive after trimming: quickbooks, xero, or microsoftbusinesscentral. Other names, including datasync, are rejected by the cloud facade.

Example request

$result = FM_api('Accounting_sync', ['provider'=>'quickbooks']);

Example response

{
  "ok": 1,
  "organisation": "Example Company",
  "sync_status": "sync completed",
  "sync_paused": 0,
  "sync_complete": 1,
  "provider": "quickbooks"
}

Database numeric values can be strings. Read the JSON error/warning fields as well as the HTTP status.

Errors and unusual responses

ResponseCondition
{"error":"not logged in"}No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
{"error":"missing or invalid parameter: provider"}The provider is absent or outside the facade whitelist.
{"error":"taxes not set up yet"}QuickBooks prerequisite settings were not found.
{"error":"A sync is already running. Please try again in a few minutes"}The QuickBooks lock is held.
{"error":"Microsoft Business Central company is not selected"}A connection exists but no company is configured.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

  • The facade appends provider and supplies ok:1 only when the returned array has no error or ok. Provider-specific fields remain intact; early provider validation errors have no provider field.
  • The facade supplies organisation and sync_status strings plus integer sync_paused/sync_complete flags, defaulting missing flags to 0. Xero and Business Central can also return a provider-specific syncs summary. Provider error details and retryable flags are preserved.
  • A request performs work synchronously; it does not merely queue a generic job. Provider helpers own locks, saved checkpoints, chunk/resume state and error handling. The CRM clients repeat paused calls and poll progress separately.
  • Sync policy all permits creation only where the phase supports it; updates requires an existing instance-scoped link; none skips the phase. Invoice downloads update linked/already-matchable Fieldmotion invoices and must not create invoices solely from accounting records. Payments are inbound; stock direction depends on provider capabilities.
  • Outbound invoice selectors apply invoice_sync_level and invoice-sync-age-limit (unset or zero defaults to 60 days). Exactly invoice_sync_level=Invoiced requires invoice status at least 1; other/unset values use All. Older invoices are logged as skipped. Credit notes require features2.accounting_credit_notes=1; legacy invoice status 4 is excluded.
  • First-sync selectors exclude inactive customers and archived stock. Existing links can propagate inactivity. Billing target is chosen at invoice creation from billing_target (-1 self, -2 parent, positive customer ID), with the invoice-to-parent fallback; this call does not globally rewrite existing billing links.
  • QuickBooks needs configured tax/service settings and uses a 600-second sync lock. Xero preserves resume state for retryable provider errors. Business Central requires a selected company and, when invoice/credit export is enabled, a revenue account; configured customer posting groups can require a customer API template.
  • A completed response is a phase-run result, not an atomic transaction across systems. Earlier remote/local writes can survive a later failure. Some legacy QuickBooks helpers terminate with their own JSON before facade normalization; handle error or sync_status responses rather than requiring one universal envelope.
  • The age cutoff compares the invoice cdate calendar date with server-local today minus the configured positive number of days, inclusively retaining the cutoff date. Nonpositive limits fall back to 60; an unparseable date is not rejected by this age helper.

Side effects

  • May read/create/update supported business objects remotely and locally; updates instance-scoped api_syncs mappings, checkpoint/resume settings, progress, provider tokens and sync logs.
  • Locks prevent overlapping provider runs while their lease is valid. This is distinct from local DataSync instruction cancellation.

See it in Fieldmotion

CRM1

Open Settings → Finances and the QuickBooks or Xero integration. Filter the browser Network panel for this Accounting route; these screens send provider explicitly. Provider-specific setup remains on the original provider routes. Click Sync; clients repeat calls when the provider reports a pause. Business Central has no CRM1 settings caller; its configuration UI is CRM2-only.

CRM2

Open Settings → Finances and the corresponding provider. The QuickBooks widget, Xero settings/background sync, and Business Central action wrapper call this facade with provider. Filter the browser Network panel for the endpoint name. Click Sync; clients repeat calls when the provider reports a pause.

Related endpoints