When to use this endpoint

Fetch/refresh catalogues first. Submit both maps together: omitting either parameter replaces that map with an empty object rather than preserving it.

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.
nominalsJSON object textNoJSON object mapping Fieldmotion nominal_code strings to remote nominal number strings; defaults to {} and replaces nominals.map. Send JSON text, not a native array.
taxesJSON object textNoJSON object mapping Fieldmotion account-category/tax IDs to remote tax name strings. Defaults to {} and replaces taxes.map; IDs differ from nominal codes.

Example request

$result = FM_api('DataSync_setNominalAndTaxMappings', ['id'=>'14', 'nominals'=>json_encode(['4000'=>'4000']), 'taxes'=>json_encode(['7'=>'T1'])]);

Example response

{
  "ok": 1
}

Database numeric values can be strings. Read the JSON error/warning fields as well as the HTTP status.

Example map identifiers are illustrative; choose codes/IDs from Accounts_list, Accounts_getCategories and the retrieved remote catalogues.

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 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.
{"error":"missing or invalid parameter: nominals"}The supplied map is not supported flat JSON. Omission still clears the corresponding map.
{"error":"missing or invalid parameter: taxes"}The supplied map is not supported flat JSON. Omission still clears the corresponding map.
{"error":"DataSync is locked. Please cancel whatever is running"}The connection is locked for agent work.
{"error":"Saved accounting codes are invalid. Refresh nominal and tax codes first."}A stored catalogue cannot be decoded to an array/object.

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

Behaviour and edge cases

  • Decodes the saved catalogue, replaces only its map member and preserves other catalogue members. Does not validate that keys/remote values exist in either system or that mapping coverage is complete.
  • Inputs must decode to flat objects whose values are strings or integers. Legacy [] is retained as empty-map clearing. Malformed JSON, null, nonempty lists, nested values and booleans are rejected. Readiness flags require at least one nonblank mapped value; whitespace around an empty object cannot mark it ready. These flags do not prove complete catalogue coverage.
  • A locked connection rejects mapping changes, so a queued catalogue refresh cannot overwrite a concurrent map save. No last_edited update, instruction enqueue or remote mapping call occurs.
  • 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.

Side effects

  • Updates both encoded catalogues and readiness flags together in a checked transaction. A failed write does not report success.

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 Set in the nominal/tax mapper; the UI serializes both maps with JSON.stringify.

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 Set in the nominal/tax mapper; the UI serializes both maps with JSON.stringify.

Related endpoints