When to use this endpoint

Create the record, generate its installer, then let the installed agent initialize/login and fetch/map nominal and tax codes. This endpoint does not install software or connect to accounting.

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
nameStringYesTrimmed nonempty name, at most 100 bytes. PHP false-like name 0 is rejected. Must not match an existing tenant name under the database collation.
sync_typeStringYesExactly sage50accounts or gnucash, case-sensitive. Cloud providers cannot be created through this route.

Example request

$result = FM_api('DataSync_new', ['name'=>'Office Sage', 'sync_type'=>'sage50accounts']);

Example response

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

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: name"}Name is empty/false-like or exceeds 100 bytes.
{"error":"missing or invalid parameter: sync_type"}Type is not an exact supported local value.
{"error":"DataSync name must be unique"}A matching tenant name was found.
{"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 is the new DataSync record ID. It will also be the agent configuration’s key_id, not a generic CRM API-key ID.
  • Creates empty encoded nominal/tax catalogues, cdate and last_edited Unix timestamps and a generated connection secret. The response does not reveal the secret; the installer embeds it.
  • Cloud accounting uses Accounting_authorisation instead. Existing historical cloud records can still appear in DataSyncs_list.
  • 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.
  • Name uniqueness and insertion are serialized with other tenant DataSync mutations; a failed or nonpositive insert does not return ok:1.

Side effects

  • Inserts one tenant datasyncs row. No instruction, mapping, local installer execution or remote OAuth call is created.

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 New and select Sage/GnuCash; the response ID becomes the settings tab identity.

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 New and select Sage/GnuCash; the response ID becomes the settings tab identity.

Related endpoints