Fieldmotion API Getting started

Settings bookmarks

Create a bookmark from mapped fields

POST /a/Link_createData

Create a bookmark from mapped editor values

When to use this endpoint

Use for the CRM2 Links editor or an integration supplying its own URL and embedding hint. Use Link_save for optional site metadata/icon discovery.

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
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

$created = FM_api('Link_createData', [
	'name' => 'Operations handbook',
	'url' => 'https://example.test/handbook/',
	'canBeEmbedded' => '0',
]);

Example response

{"ok":1,"id":1042}

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.
{"error":"missing or invalid parameters."}No writable non-null mapped values.

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

Behaviour and edge cases

  • At least one non-null writable value is required; id alone fails. No field is individually mandatory. Unknown request fields and id are ignored; noRecord/noRecordCustom are rejected.
  • Omitted owner becomes zero for a client administrator and the acting user ID for other users. Omitted canBeEmbedded uses the schema default 1; omitted name/url can be null.
  • Each successful call creates a new row. There is no duplicate detection or idempotency key; refresh after an uncertain response before creating again.
  • 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 Add/Edit Links 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