When to use this endpoint

For an ordinary reconnect, preserve links by omitting clear. Use clear=yes only when intentionally rebuilding that provider instance’s mappings; it does not delete the business objects themselves.

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.
sureStringYesMust be exactly yes; checked before provider validation or login.
clearStringNoExactly yes requests current-instance mapping cleanup. Every other value preserves links.

Example request

$result = FM_api('Accounting_disconnect', ['provider'=>'quickbooks', 'sure'=>'yes']);

Example response

{
  "ok": 1,
  "provider": "quickbooks",
  "cleared_links": 0
}

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":"sure is not yes"}Confirmation is absent or differs in case/value.
{"error":"A sync is already running. Please try again in a few minutes"}QuickBooks has a fresh sync lock.
{"error":"sync already active. please try again soon."}Xero or Business Central has an active sync/disconnect mutex.

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.
  • cleared_links reflects the requested clear flag on a successful handler response, not a count of deleted mappings. Ordinary disconnect leaves api_syncs object links intact.
  • QuickBooks retains its trusted realm scope before credential removal for clear=yes cleanup, and rejects a fresh sync lock (older than 600 seconds can be cleared). Tenant mappings are restricted to the captured instance. Legacy global api_syncs cleanup is tenant/provider-wide rather than instance-scoped. Cleanup can fail after credentials have already been removed.
  • Xero attempts remote disconnection, removes the global OAuth link for its saved tenant ID, clears local Xero settings and optionally its instance-scoped mappings. If remote cleanup fails, local cleanup still proceeds and warning/remote_error fields describe the partial result.
  • Business Central removes its sync_microsoftbusinesscentral_ settings except the owned mutex, and optionally current-instance mappings. This path does not call remote OAuth revocation. Xero and Business Central acquire their existing sync mutex before cleanup and release it on success or exception; a fresh active sync refuses disconnect.
  • QuickBooks attempts remote revocation but logs a revocation failure as debug and still clears local credentials without returning that failure to the caller.
  • Xero retains its owned mutex while removing other Xero settings. Business Central likewise retains its mutex until disconnect exits. The provider mutex is shared with legacy direct provider calls, not just the facade.

Side effects

  • Can revoke remote credentials, remove local tokens/settings/OAuth associations and, with clear=yes, delete sync mappings. It does not reverse prior invoice/payment changes or delete remote business objects.

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. Choose Disconnect and confirm; the UI sends sure=yes and the selected clear-links option. 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. Choose Disconnect and confirm; the UI sends sure=yes and the selected clear-links option.

Related endpoints