Retrieve picklist choices by business value

When to use this endpoint

Use when a customer/job stores a CommonList business value and the UI needs its label. This endpoint remaps id/ids selectors and returned id values; it is not a physical-row lookup.

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
`value`	Integer string or native array	No	Business value(s) to resolve. Add type to disambiguate values reused across namespaces.
`id / ids`	Integer string or native array	No	If value is absent, id or ids is moved into value and no longer selects the physical row. If value is explicitly supplied as well, id/ids still applies as an additional physical-row selector.
`fields`	Native array of strings	No	Selectable 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`. The handler appends value before calling the shared reader, so omission selects only value plus id, not the full map. JSON-string field lists are not decoded.
`Mapped field filters`	Scalar or native array	No	Include type for exact trimmed case-insensitive namespace matching; other text filters also use equality, integers equality/membership. Empty numeric arrays match none.
`order`	Field string or native array	No	Mapped ascending field(s) or objects with id and dir=desc. No default order or request-ID order preservation.
`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.

Example request

$choices = FM_api('CommonList_getRequestedDetails', [
	'id' => '10001',
	'type' => 'contactType',
	'fields' => ['name', 'metaColor'],
]);

Example response

[{"name":"Site contact","metaColor":"blue","value":"10001","id":10001}]

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.
`[]`	No matching choice or shared reader database failure; these are indistinguishable.
`{"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

value is always included as a database string; returned id is overwritten with its integer conversion. Multiple types can return the same id if type was not filtered.
No required/default/active restriction is added. Omitting selectors can return all choices; empty id/ids becomes an empty numeric value filter and matches none.
No pagination or limit. Raw meta remains encoded JSON; derived metaColor/metaOrgName values are extracted by the reader. cdate and lastEdited render as SQL datetime strings, despite Unix storage.
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. List pickers explicitly pass type when resolving saved business values; bulk settings actions also request required before deletion.

Related endpoints

CommonLists_getDataTable returns physical IDs unless valueToID is present.
CommonList_updateData requires physical storage-row IDs.