When to use this endpoint

Call after completing OAuth and before offering Sync or Disconnect. A connected state is not proof that required mapping and company configuration is complete.

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_status', ['provider'=>'quickbooks']);

Example response

{
  "ok": 1,
  "state": 1,
  "organisation": "Example Company",
  "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.

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.
  • state is integer-normalized, defaulting to 0, and organisation is string-normalized, defaulting to empty, even on normalized provider errors. QuickBooks and Xero use 0/1 connection state; Business Central also returns company_id, company_name, user_name and environment (default Production).
  • Xero additionally returns org data and scope-status fields. scope_status is current, needs_update, unknown or disconnected; permissions_update_required is advisory and an older grant alone does not block sync.
  • There is no record ID, pagination or object filtering. Status concerns the authenticated tenant’s saved provider connection.

Side effects

  • QuickBooks/Xero/Business Central status helpers may make remote calls, refresh expired tokens and persist refreshed credentials. This is not a database-only health read.

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. Open the provider settings page or finish the consent popup; status controls the connection display. 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. Open the provider settings page or finish the consent popup; status controls the connection display.

Related endpoints