Fieldmotion API Getting started

Settings bookmarks

Update one bookmark field

POST /a/Link_updateField

Change one mapped bookmark field across explicit IDs

When to use this endpoint

Use for a single-field change with prior values in the acknowledgement. Link_updateData is the multi-field counterpart.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. All bookmark endpoints require Settings Links View (pageSettingsLinks_view); client administrators pass the standard permission helper. Missing permission fails closed. An API key acts as its associated user.

The authenticated tenant owns the rows. Reads expose userID=0 (shared) and the acting user’s rows, even for admins. Writes to existing rows require ownership unless the actor is a client administrator; non-admins cannot edit/delete shared rows. No bookmark-specific tenant setting, department filter or separate create/edit role is consulted.

Parameters

ParameterTypeRequiredDescription
id / idsPositive integer or native arrayYesid takes precedence over ids when non-null. Require canonical positive integer IDs; encoded JSON, empty arrays, zero, negative, malformed and overflowing IDs fail. At most 1000 entries; duplicates are removed and IDs sorted.
fieldMapped aliasYesname, url, userID or canBeEmbedded. Primary id is not writable.
valField-dependent scalarYesNon-null replacement (not value). Same ownership, active-user and 0/1 rules as mapped writes; empty text is accepted.

Example request

$result = FM_api('Link_updateField', ['id'=>'1042','field'=>'name','val'=>'Revised handbook']);

Example response

{"ok":1,"oldData":[{"id":"1042","name":"Operations handbook"}]}

oldData contains selected IDs and the underlying column before change (user_id or can_be_embedded for those aliases). All-unchanged requests return {"ok":"1","warning":"no change required"}.

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":"permission denied"}Missing page access, non-owned existing write target, or forbidden ownership assignment.
{"error":"missing or invalid parameter: id/ids"}Invalid explicit ID selector; absent required selectors can instead report missing or invalid parameter: id.
{"error":"Bookmark not found or not editable"}An update target does not exist.
{"error":"Unable to save bookmark changes. Check the saved state before retrying."}Failed database/history operation or uncertain commit. Read failures instead return Unable to read bookmarks.

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

Behaviour and edge cases

  • Targets the canonical lowercase links table. Every selected ID must exist and be editable. The entire multi-ID update/history operation rolls back on failure; a failed read cannot masquerade as a no-op.
  • Native request arrays are required where stated; JSON strings are not decoded. No direct mobile app/m-service caller for this Settings-bookmark family was found. Bookmark IDs are unrelated to document share tokens.

Side effects

  • Writes tenant links and invalidates its cache. Creation and changed mapped fields receive individual tenant history rows with acting-user attribution; deletion records a deletes audit. Database changes and history are transactional, including a multi-ID batch. A failed read, write or history operation fails the request and rolls back the batch. An uncertain commit is not automatically replayed: refresh before retrying.

See it in Fieldmotion

CRM1

No direct production caller found; its editor uses Link_save.

CRM2

No direct production caller found; the current editor uses Link_updateData.

Related endpoints