When to use this endpoint

Read current modes first. A transition from none to all/updates starts from now rather than replaying the disabled interval.

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
providerStringYesTrimmed, lowercased quickbooks, xero, microsoftbusinesscentral or datasync.
datasync_idInteger-compatibleFor datasyncPositive DataSync record ID for provider=datasync. The stored type must be sage50accounts or gnucash. For cloud providers the value is echoed but does not change policy scope; omission becomes 0.
modesJSON object text or native arrayYesNonempty phase-key → mode map. Omitted phases are preserved. Values are trimmed/lowercased all,updates,none; 1/yes/on/true normalize to all and 0/no/off/false to none. Unknown phase keys or modes are rejected.

Example request

$result = FM_api('Accounting_syncPolicySet', ['provider'=>'datasync', 'datasync_id'=>'14', 'modes'=>json_encode(['customers_up'=>'updates'])]);

Example response

{
  "ok": 1,
  "provider": "datasync",
  "datasync_id": 14,
  "sync_type": "gnucash",
  "phases": [
    {
      "key": "customers_down",
      "mode": "all",
      "object": "customers",
      "direction": "down",
      "label": "Customers"
    },
    {
      "key": "invoices_down",
      "mode": "all",
      "object": "invoices",
      "direction": "down",
      "label": "Sales Invoices"
    },
    {
      "key": "customers_up",
      "mode": "updates",
      "object": "customers",
      "direction": "up",
      "label": "Customers"
    },
    {
      "key": "invoices_up",
      "mode": "all",
      "object": "invoices",
      "direction": "up",
      "label": "Sales Invoices"
    }
  ]
}

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":"missing or invalid parameter: modes"}Missing, malformed, empty or non-array modes.
{"error":"unsupported sync phase: example"}A phase is not supported for this provider/type.
{"error":"invalid sync mode for customers_up"}The supplied mode is not recognized.
{"error":"missing or invalid parameter: datasync_id"}Local policy requires a positive record ID.
{"error":"DataSync does not support selective sync"}The record is absent or not a local type.
{"error":"Unable to save accounting policy. Reload the policy before retrying."}A database read/write/commit failed; do not infer success from a previous editor state.
{"error":"Accounting policy is busy. Please try again."}Another save holds this policy’s lease.

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

Behaviour and edge cases

  • Response is ok,provider,datasync_id,sync_type,phases. Cloud sync_type is empty. Each phase has key,mode,object,direction,label; down means accounting → Fieldmotion and up means Fieldmotion → accounting. No pagination or record filters apply.
  • Cloud phase keys, in response order: customers_down, suppliers_down, stock_down, invoices_down, payments_down, customers_up, suppliers_up, stock_up, invoices_up, credit_notes_up. These are shared policy capabilities, not a promise that every provider implements every object or that a tenant feature is enabled.
  • Sage phases omit suppliers_down and suppliers_up. GnuCash returns only customers_down,invoices_down,customers_up,invoices_up. A nonexistent or historical cloud DataSync ID returns DataSync does not support selective sync.
  • Modes: all allows create/update where the phase supports it; updates requires an existing instance-scoped api_syncs mapping and does not name-match/create; none skips the phase. Invoice downloads remain update-only regardless of all.
  • Unset modes default to all; Business Central imports its legacy phase switches as defaults. Policy is tenant/provider-scoped, and local policy additionally uses the DataSync record ID. It is not a per-user preference.
  • Only phases transitioning from none to an enabled mode advance their checkpoint. all ↔ updates leaves it unchanged. Xero/Business Central adjust phase clocks; QuickBooks adjusts the active global connection metadata; DataSync adjusts datasyncLastChecked<ID> phase entries. A checked persistence failure stops the save and rolls back open transactions.
  • Re-enable clocks use server now in each provider’s expected Unix/SQL/UTC format. Disabled-period changes are skipped by this mechanism; this is not a full-history resync switch.
  • A tenant/provider lease serializes policy saves. Tenant policy and phase settings use one checked transaction. QuickBooks retains a separate global checkpoint connection: its writes are checked and open transactions are rolled back on failure, but commits across global and tenant databases are not a distributed atomic transaction. On any uncertain save result, reload policy and review checkpoints before retrying.

Side effects

  • Writes the tenant/provider policy setting and invalidates its settings cache; can advance several phase checkpoints. Does not start remote or agent work.

See it in Fieldmotion

CRM1

Source search found no direct CRM1 policy-widget caller. Its Finance/Data Sync screens use the configured sync paths; the API policy is shared server state.

CRM2

In Finance provider settings or local Data Sync settings, open the selective-sync widget. widgetAccountingSyncPolicy sends provider and, for local agents, datasync_id; saving sends modes as JSON text. Filter Network requests for Accounting_syncPolicyGet/Set.

Related endpoints