Fieldmotion API Getting started

Settings bookmarks

Edit mapped bookmark fields

POST /a/Link_updateData

Update mapped fields on one or more editable bookmarks

When to use this endpoint

Use after selecting bookmark IDs from a list or detail lookup. Supply only fields that should change; the whole selected batch is validated and committed together.

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.
nameStringNoStored label; scalar values convert to text. No trim, nonblank or maximum-length constraint in mapped writes. Null/unknown fields are ignored.
urlStringNoStored text without URL syntax, HTTP prefix or destination validation in mapped writes. No remote request is made.
userIDNonnegative integerNoZero means account-shared. Positive owners must be active tenant users. Non-admins may only supply their own user ID; administrators may supply zero or an active owner.
canBeEmbedded0 or 1NoOnly integer/string 0 and 1 accepted. Stored rendering hint; it does not prove a browser can embed the target.

Example request

$result = FM_api('Link_updateData', ['id'=>['1042','1088'], 'name'=>'Revised handbook']);

Example response

{"ok":1}

A scalar-ID no-op returns {"warning":"No Change."}, or {"warning":"no updated fields."} when no writable fields were supplied. Array-ID batches return ok=1 even when unchanged.

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

  • Every selected ID must exist and be editable before any changes commit. An absent/non-owned row fails the batch. Admins may update other owners; non-admins cannot transfer ownership to another user or to shared.
  • Null/unknown writable fields are ignored; noRecord/noRecordCustom are rejected. Text comparisons are strict; owner/embedding values compare numerically. There is no optimistic lock, timestamp or idempotency token.
  • 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 production CRM1 caller found; its dialog uses Link_save.

CRM2

CRM2 Settings → Links uses widgetDisplayStyle with Link/Links prefixes: Links_getDataTable lists rows, Link_createData creates them and the mapped detail/update endpoints edit them. Its Delete action submits explicit IDs to Links_deleteData and announces success only after acknowledgement; failures refresh the table and show an error.

Related endpoints