List configurable picklist choices

When to use this endpoint

Use to enumerate a namespace, such as customer contact types. Preserve physical IDs for maintenance; turn on valueToID only for a picker that stores business values.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login, without an additional list-management/page/role permission check. Lists belong to the authenticated tenant, not an individual user.

Parameters

Parameter	Type	Required	Description
`fields`	Native array of strings	Yes	Selected mapped fields; unknown names ignored and id automatically included. A JSON-encoded string is not decoded.
`start / length / draw`	Integer strings	No	Defaults start=0, length=10, draw=0. start must be nonnegative and length positive; no upper cap or -1 all-rows convention. draw must be an integer.
`isTable / limit`	Integer strings	No	isTable=0 disables table paging/counts; limit then caps rows only if positive, otherwise unbounded. Default table mode ignores limit.
`orderBy / orderDesc`	Strings	No	Provide both: mapped sort key and direction asc or desc (case-normalized). Other directions are rejected.
`order`	Native DataTables array	No	Alternative first-entry column/dir sort. The column index is reduced by one, floored at zero, and selects from fields. Default is first recognized selected field ascending. No ID tie-breaker.
`searchValue / searchField`	String / native array or string	No	Nonblank case-insensitive substring search, over All by default or specified mapped fields. SQL LIKE wildcards remain meaningful.
`groupBy`	Native array of mapped names	No	Generic SQL grouping control. No aggregate fields are supplied here; avoid it for ordinary table pagination. Counts do not incorporate grouping.
`advanceSearch`	Native array	No	Native list of structured rules: column (or id), condition, value, optional andOr=AND/OR and balanced special=(/) grouping. Operators: equal, notEqual, contains, greaterThan, greaterThanOrEqual, lesserThan, lesserThanOrEqual. Raw where clauses are rejected.
`Mapped field filters`	Scalar or native array	No	Keys: `id` (physical row ID), `type` (list namespace), `name`, `value` (business choice ID), `required` (integer), `meta` (JSON), `metaColor` (`meta.color`), `metaOrgName` (`meta.orgName`), `cdate`, `lastEdited`. type/name/text scalars use trimmed case-insensitive substring matching, not exact matching; native string arrays use membership. Integer values use equality/membership.
`valueToID`	Any present nonnull value	No	Presence enables remapping, even string 0. Appends value to selected fields and overwrites each id with integer value. Omit entirely for physical row IDs.
`referenceDate / dateFrom / dateTo`	Mapped date name / integer day offsets	No	Reference cdate or lastEdited; inclusive relative-day range if both offsets are supplied. Tenant timezone determines today (fallback UTC); values are Unix-backed.
`offsetFrom / offsetTo`	Native hour/minute objects	No	Optional reference-date offsets; hour is negated, minute added by the shared helper. Datetime arithmetic uses PHP server handling.
`timeRangeFrom / timeRangeTo`	Integer hours	No	Inclusive reference-date hour range in tenant timezone (fallback Europe/London). Only timeRangeFrom triggers the range; timeRangeTo alone is ignored.

Example request

$choices = FM_api('CommonLists_getDataTable', [
	'fields' => ['name', 'value', 'required'],
	'type' => ['contactType'],
	'start' => '0', 'length' => '25', 'draw' => '1',
]);

Example response

{"data":[{"name":"Site contact","value":"10001","required":"0","id":"1042"}],"draw":1,"recordsTotal":"8","recordsFiltered":"1"}

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":"missing or invalid parameter: fields"}`	Selected field array omitted.
`{"error":"error in database query"}`	Primary query fails.
`{"error":"unsupported raw advanced search"}`	A raw where rule was supplied.
`{"error":"missing or invalid parameter: orderDesc"}`	An unsupported sort direction was supplied.

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

Behaviour and edge cases

Mapped fields: id (physical row ID), type (list namespace), name, value (business choice ID), required (integer), meta (JSON), metaColor (meta.color), metaOrgName (meta.orgName), cdate, lastEdited. The map always appends physical id unless valueToID rewrites it. No default type or required-only filter; omitting type lists all tenant namespaces.
Table mode defaults to ten rows. recordsTotal counts all choices across all namespaces; recordsFiltered includes type and other request filters. Non-table isTable=0 returns only data and is unbounded unless limit is positive.
cdate/lastEdited are returned as SQL datetime strings; meta is encoded JSON, derived aliases are scalar JSON values. No ID tie-breaker is added to sorting.
Raw advanced-search SQL, unsafe directions, non-list field controls, nested filter values and malformed pagination/date-offset controls return structured errors before the query. Structured advanced-search grouping must be balanced.

See it in Fieldmotion

CRM1

No direct CRM1 caller to this CommonList route was found in the source search. CRM2 uses these generic list endpoints for configurable customer contact types, job sub-statuses, purchase statuses and contract stages.

CRM2

Open CRM2 customer settings → Contact Types. pageSettingsContactTypes.js uses CommonList/CommonLists widget prefixes and shared create/detail/edit helpers. Filter the Network panel for this endpoint. The settings table uses physical IDs; list-picker configurations may pass valueToID and then resolve labels by value.

Related endpoints

CommonList_getRequestedDetails resolves one or more business values.
CommonList_createData allocates a new choice value.
CommonList_updateData edits by physical ID.