Fieldmotion API Getting started

Saved views and configuration

Update one mapped preset field

POST /a/UserFilter_updateField

Set a single mapped field on selected filter rows and return their prior stored values.

When to use this endpoint

Use to replace one mutable preset field across selected authorized rows. The primary ID and creation date are read-only; assigning another owner is administrator-only.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. A tenant login is required.

Reads expose only filters owned by the current user or marked public=1. Writes require ownership or client-administrator permission; another user’s public filter is not editable merely because it is visible. Assigning or transferring ownership to another active tenant user requires client-administrator permission.

Parameters

ParameterTypeRequiredDescription
id / idsPositive integer string or nonempty native listYesEvery physical target must exist and be authorized. id takes precedence. Empty lists and unknown IDs are rejected.
fieldStringYesMutable keys: name (nonempty, max 182 characters), pageType (nonempty, max 80 characters), userID (positive active owner), data/meta (native JSON or valid JSON text), public (boolean/0/1/true/false). JSON replaces the whole column. Creation date and primary ID cannot be edited; id is only a selector.
valScalar or native JSON valueYesReplacement value for the mutable key. Null is rejected.

Example request

$result = FM_api('UserFilter_updateField', ['id' => '1088', 'field' => 'name', 'val' => 'Northwind jobs']);

Example response

{"ok":1,"oldData":[{"id":"1088","name":"Previous preset name"}]}

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"}IDs must be positive integers; malformed/missing selectors are rejected.
{"error":"filter with that ID does not exist"}Any selected target is absent.
{"error":"filter permission denied"}A non-administrator targets another owner or attempts an unauthorized owner assignment.
{"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

  • All selected rows are locked and authorized before mutations. The batch commits atomically; a missing/unauthorized target or later write/history failure leaves earlier rows unchanged.
  • Unspecified fields remain unchanged. Unknown updateData keys are ignored; updateField rejects unknown or read-only keys. Supplied cDate in updateData is rejected. Ownership transfer to another user is administrator-only.
  • No last-edited column is added; creation time is preserved.
  • oldData includes every selected row using physical column names. Equal normalized values return {"ok":"1","warning":"no change required"}; successful changes return ok and oldData.

Side effects

  • Changed rows request their table’s cache marker. Row changes and history commit in one checked transaction; a write, history or commit failure rolls back the batch.
  • No customer/job data, notification or email is changed. No tenant feature setting alters this endpoint’s behavior.

See it in Fieldmotion

CRM1

No direct CRM1 caller for this mapped route was found. CRM1 Settings → Filters uses UserFilters_getDT, UserFilter_setName, UserFilter_setPublic and UserFilter_delete.

CRM2

No screen-specific CRM2 call to this route was found. The shared updateField helper can construct it dynamically, but the observed Settings → Filters table and bulk privacy action use UserFilter_updateData.

Related endpoints