Fieldmotion API Getting started

Saved views and configuration

Merge preferences into several pages

POST /a/PageSettings_updateMultiPage

Save multiple pages’ field/value mappings in one request.

When to use this endpoint

Use when one CRM2 display-settings action updates several page or modal preference groups. Every supplied page is saved in one checked transaction.

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
pagesNative mapping or JSON object stringYesPage-to-field/value mapping. Each inner mapping may itself be JSON-encoded. Page and field keys are nonempty and at most 100 characters; values use the singular writer’s encoding and 65535-byte limit.

Example request

$result = FM_api('PageSettings_updateMultiPage', [
	'pages' => json_encode([
		'pageJobs' => ['length' => '25'],
		'pageTasks' => ['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: pages"}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

Save CRM2 table display settings or job-file modal display options. widgetFilesTable.js passes a native page-to-fields mapping; the table modules use the same multi-page route.

Related endpoints