Fieldmotion API Getting started

Saved views and configuration

Merge preferences into one page

POST /a/PageSettings_update

Save selected preference fields without removing the page’s other fields.

When to use this endpoint

Use from a screen that changes several display options together. This merges keys; it does not replace all settings or delete omitted keys.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Ordinary page keys, including the literal string false, use the current user; pageLayouts and pageGlobal use tenant-shared user ID 0.

Shared reads need no additional permission. Only the account administrator (user ID equals parent account ID) can write pageLayouts. pageGlobal retains its existing shared-write access for authenticated users.

Parameters

ParameterTypeRequiredDescription
pageStringYesNonempty page key, maximum 100 characters. pageLayouts and pageGlobal are shared; other keys are current-user specific.
fieldsNative mapping or JSON object stringYesField-to-value mapping. Keys must be nonempty and at most 100 characters; values use the singular writer’s encoding and 65535-byte limit.

Example request

$result = FM_api('PageSettings_update', [
	'page' => 'pageJobs',
	'fields' => json_encode(['length' => '25', 'columns' => ['id', 'name']]),
]);

Example response

{"ok":1}

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: fields"}Required mapping is absent or malformed; invalid keys/values return corresponding validation errors.
{"error":"Page cannot be updated."}A non-account-administrator includes pageLayouts; the whole batch is rejected.
{"error":"configuration read failed"}A required database read fails; no write is committed.
{"error":"configuration write failed"}Persistence or checked history fails; the transaction rolls back.
{"error":"configuration transaction failed"}Transaction begin or commit fails; no success is reported.

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

Behaviour and edge cases

  • Merges supplied keys without deleting omitted keys. Empty mappings are successful no-ops; malformed JSON is rejected.
  • The full payload and every page permission are checked before writing. Any forbidden pageLayouts entry rejects the whole batch; it is never silently skipped. Persistence, history and commit failures roll back all page changes.
  • pageLayouts and pageGlobal both use shared scope in every writer. Native structures encode as JSON; booleans encode as true/false tokens. Exact stored-text equality skips writes.
  • Tenant-serialized upserts prevent new duplicate keys. Existing duplicates for a supplied key are updated consistently. No feature flag or business key allowlist is applied.

Side effects

  • Changed page_settings rows request the cache marker; shared changes record checked history. Every supplied page commits in one transaction.
  • No last-edited timestamp, notification or business data mutation.

See it in Fieldmotion

CRM1

No direct CRM1 production caller was found. These routes underpin CRM2 server-stored display preferences; CRM1 also keeps client-side display/filter state.

CRM2

CRM2 loads page preferences when opening a table or edit screen. Shared helpers saveSettings/saveSetting in lib.js persist display choices; filter the Network panel for this exact route. pageCustomerOverview.js saves widget settings with this bulk route.

Related endpoints