Settings bookmarks
Read mapped bookmark details
/a/Link_getRequestedDetails
Read selected bookmark fields within the visible collection
When to use this endpoint
Load selected bookmarks for an editor, or read the visible collection with mapped equality filters. The result is a bare array, even for one ID.
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
| Parameter | Type | Required | Description |
|---|---|---|---|
id / ids | Positive integer or native array | No | id 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. Omission leaves the shared/current-user visibility filter in place. |
fields | Native array | No | Defaults to id, userID, name, url, canBeEmbedded. Unknown aliases are skipped; id is always included. Empty array selects id only. Encoded JSON text is rejected. |
name / url | Scalar or native array | No | Detail reads use trimmed case-folded equality. Table scalar filters use trimmed case-folded LIKE substrings; table arrays use equality. % and _ remain LIKE wildcards. Empty filter arrays match nothing. |
userID / canBeEmbedded | Numeric scalar or native array | No | Equality, or OR-combined equality for arrays. Other filters combine with AND. These filters cannot widen visibility; empty arrays match nothing. |
advanceSearch / groupBy / referenceDate / dateFrom / dateTo / timeRangeFrom / timeRangeTo / offsetFrom / offsetTo | Unsupported controls | No | Non-null values other than an empty native array are rejected. There is no bookmark date/group/layout query contract or raw SQL escape hatch. |
order | Alias or native array | No | Alias(es) or entries such as [{id:name,dir:desc}]. Only mapped aliases and asc/desc accepted; an ID tiebreaker is added. No default ordering. start/length do not paginate detail reads. |
Example request
$rows = FM_api('Link_getRequestedDetails', ['id'=>['1042'],'fields'=>['id','name','url']]);Example response
[{"id":"1042","name":"Operations handbook","url":"https://example.test/handbook/"}]Errors and unusual responses
| Response | Condition |
|---|---|
{"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
- Only shared/current-user rows are returned, including for admins. Unmatched or invisible IDs are omitted; no match returns []. Read failures return error rather than an empty collection.
- All filters combine with AND. No URL lookup, joins, date/deleted/department filter or access timestamp is added. Database scalar types are retained, commonly strings and nullable stored text.
- 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
- Reads tenant bookmarks only.
See it in Fieldmotion
CRM1
No production caller found. Its positional list supplies values for the edit dialog.
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
- Link_save performs optional site/icon discovery; Link_createData stores mapped values directly.
- Link_getRequestedDetails returns a bare array; Links_getDataTable returns a table envelope.
- Link_updateData changes multiple fields; Link_updateField changes one.
- Link_delete removes one bookmark; Links_deleteData handles an explicit batch.
- LinkShareable_new creates a bearer document/file URL, a separate workflow.