When to use this endpoint

Read the connection state, queue this action, then poll the returned instruction ID until the agent marks it done.

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
idInteger-compatibleYesPositive DataSync record ID from DataSync_new or DataSyncs_list, not an instruction ID.

Example request

$result = FM_api('DataSync_logout', ['id'=>'14']);

Example response

{
  "ok": 1,
  "id": 82
}

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: id"}Missing, zero or negative ID.
{"error":"DataSync does not exist"}No matching tenant DataSync.
{"error":"cloud Data Sync is retired and no longer available"}The stored sync_type is not sage50accounts or gnucash.
{"error":"DataSync is locked. Please cancel whatever is running"}The saved locked value is nonzero; the operation is not queued.
{"error":"datasync is either already logged out, or agent needs to be updated"}The saved login state is not the required value.
{"error":"DataSync settings are busy. Please try again."}Another tenant DataSync mutation owns the lease.
{"error":"Unable to save DataSync changes. Please reload before retrying."}A transaction/read/write/commit failed. Reload saved state before retrying.

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

Behaviour and edge cases

  • id in the success response is a new instruction ID. Poll DataSync_getInstruction with that ID, not the original connection ID. The agent later updates logged_in; this handler does not.
  • Writes an encoded method/params instruction, sets locked=1 and last_edited to Unix now. The agent retrieves work through the separate Data Sync service, not by calling this CRM polling endpoint.
  • An installed, reachable agent is required to complete the request. There is no wait timeout, completion payload or direct accounting login in this handler.
  • The saved logged_in value must be 1; a new -1/uninitialized agent state is rejected. Only sage50accounts and gnucash records are accepted.
  • Uses a tenant mutation lease and a checked database transaction. Queue, mapping and connection-creation writes commit together or return an error with rollback. Busy requests must be retried after reloading; an uncertain commit requires a fresh read before retrying.
  • Both saved locked state and unfinished instructions for the connection prevent duplicate queueing. The connection row is locked while validating and writing.

Side effects

  • Inserts the instruction and marks the connection locked in one checked transaction. The agent later performs the accounting action.

See it in Fieldmotion

CRM1

Open Settings → Data Sync. The pageSettingsDataSync screen uses this route for the operation described above; filter browser Network requests by the exact function name. Local-agent setup is separate from the cloud Finance integrations. Click Logout; the UI polls the returned instruction ID and reloads on status 3.

CRM2

Open Settings → Data Sync. The CRM2 pageSettingsDataSync screen retains this local-agent workflow; filter browser Network requests by the exact function name. Its screen permissions do not add a role check to this shared handler. Click Logout; the UI polls the returned instruction ID and reloads on status 3.

Related endpoints