Cloud accounting and selective sync
Check the cloud accounting connection
/a/Accounting_status
Read the selected provider’s connection and organization state.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
provider | String | Yes | Case-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
| Response | Condition |
|---|---|
{"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
Accounting_authorisation— Start or renew provider consent.Accounting_progress— Poll the saved progress message.Accounting_sync— Execute cloud phases.