When to use this endpoint

After login, logout or remote catalogue fetch, pass the returned id here. A DataSync record ID with the same number is unrelated.

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_instructions row ID, returned by a queuing call.

Example request

$result = FM_api('DataSync_getInstruction', ['id'=>'82']);

Example response

{
  "ok": 1,
  "instruction": {
    "id": "82",
    "api_key_id": "14",
    "cdate": "1794474000",
    "done_date": "0",
    "instructions": "{\"method\":\"login\",\"params\":[]}",
    "status": "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: id"}Missing, zero or negative ID.
{"error":"Instruction does not exist"}No matching tenant instruction ID.

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

Behaviour and edge cases

  • Returns the whole tenant instruction row. api_key_id is the owning DataSync record ID; instructions stays JSON-encoded text; cdate and done_date are Unix seconds. No wait, pagination or parent-ID parameter is provided.
  • Observed protocol: status 0 queued, 1 received by the agent, 3 marked done by setInstructionDone. Tenant-wide cancellation uses status 2 and sets done_date. Done is a protocol acknowledgement, not a detailed per-object accounting result.
  • The lookup is by instruction ID only, without filtering to a current user or selected DataSync. CRM1 and CRM2 poll status 1/3, then reload the connection/catalogue.
  • Agent 25 also acknowledges a caught accounting-login failure through setInstructionDone, producing status 3 while remaining logged out. Reload DataSync_get and inspect DataSync_getLogs; status 3 alone does not prove successful login.
  • The Data Sync service accepts completion only for this connection’s active instruction (or a retry of its completed acknowledgement). It cannot overwrite a cancelled instruction with status 3.

Side effects

  • Read only; polling does not acknowledge, consume, unlock or execute the instruction.

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 Login, Logout or refresh codes; the UI polls using the queued instruction’s ID.

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 Login, Logout or refresh codes; the UI polls using the queued instruction’s ID.

Related endpoints