Fieldmotion API Getting started

Settings bookmarks

Query mapped bookmark rows

POST /a/Links_getDataTable

Filter and page visible bookmarks as mapped rows

When to use this endpoint

Use for CRM2 Links tables. Named fields and server offset paging differ from the positional, fully downloaded Links_getDT result.

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 arrayNoid 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.
fieldsNative arrayYesDefaults 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 / urlScalar or native arrayNoDetail 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 / canBeEmbeddedNumeric scalar or native arrayNoEquality, 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 / offsetToUnsupported controlsNoNon-null values other than an empty native array are rejected. There is no bookmark date/group/layout query contract or raw SQL escape hatch.
isTableInteger-converted modeNoDefaults to table mode; integer zero returns only {data:[...]} without draw/counts.
start / length / drawIntegersNoTable defaults 0/10/0. start is nonnegative offset, length positive and capped at 1000; -1 is rejected, not all rows. draw integer-converts.
limitNonnegative integerNoUnpaged mode only; zero/omitted means unlimited, positive caps at 1000.
searchValue / searchFieldString / alias or native arrayNoNonblank trimmed LIKE search, case-folded, across aliases (default All). Search fields OR together then AND with filters; unknown search aliases contribute no predicate.
orderBy / orderDesc / orderMapped sort controlsNoTable mode: both orderBy and orderDesc (asc/desc), or DataTables order[0][column] projected index minus one, clamped to zero, with dir asc/desc. Defaults to first selected field ascending. ID ascending is appended as tiebreaker. Unpaged mode does not sort.

Example request

$table = FM_api('Links_getDataTable', ['fields'=>['id','name','url'],'start'=>'0','length'=>'10','draw'=>'1']);

Example response

{"data":[{"id":"1042","name":"Operations handbook","url":"https://example.test/handbook/"}],"draw":1,"recordsTotal":"4","recordsFiltered":"1"}

Counts are strings: total is the shared/current-user collection before request filters; filtered is after filters and before paging. Database scalar types are retained. Unpaged mode returns only data.

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

  • Visibility always restricts rows and both counts, including for admins; caller owner filters cannot widen it. Offset paging has no snapshot token, so concurrent writes can move boundaries.
  • CRM2 safely renders URL text and allowlists browser href protocols. This does not rewrite stored URL text or make mapped writes perform discovery.
  • 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 rows/counts only, without URL fetches, history or icon refresh.

See it in Fieldmotion

CRM1

No production caller found. Its Links table uses Links_getDT.

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