List selectable tenant users · Fieldmotion API

When to use this endpoint

Use for dropdowns, timelines and scheduler user selection. Default fields are always id, name and active; requested fields are additive rather than a replacement projection.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. Session requests use the dispatcher’s CSRF protection when configured.

Configured TeamAccess row scope is applied in the queries. Ordinary collection requests do not need artificial record IDs. Explicit IDs still pass dispatcher record authorization; unavailable IDs can be rejected there rather than silently omitted.

Financial fields require client administrator, explicit Users Edit, or the legacy Salaries permission (general permission bit value 8). Unauthorised list projections omit those fields; explicitly requested table/export financial fields return a permission error.

Parameters

Parameter	Type	Required	Description
`fields`	Native or JSON-encoded list	No	Optional flat native/JSON string list from the documented allowlist. id,name,active are always selected. Financial/permission fields are omitted without the required authority. Unknown names are ignored.
`ids`	JSON list or native list	No	Optional flat positive IDs/digit strings. Omitted means all visible eligible users; [] means none. Malformed values return invalid parameter: ids.
`active`	Integer string	No	Optional nonnegative integer status; omitted includes active and inactive users. Blank/nonnumeric values return invalid parameter: active.
`last_edited`	Datetime string	No	Strictly greater than this value and strictly below current server datetime. Not an inclusive sync checkpoint.
`departments`	Integer flag	Legacy	Nonzero requests the stored departments column; it does not filter memberships.

Example request

$result = FM_api('Users_list', [
	'fields'=>['email', 'skills'],
	'active'=>'1',
]);

Example response

[
  {
    "id": 1042,
    "name": "Alex Morgan",
    "active": "1",
    "email": "alex@example.test",
    "skills": [
      {
        "id": 18,
        "multiplier": 0.5
      }
    ]
  }
]

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":"invalid parameter: example"}`	A supplied native control is malformed; the response names that control. Lists must be flat, and numeric IDs must be positive integers unless the parameter explicitly permits zero.

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

Behaviour and edge cases

Excludes any user whose meta.is_tmp is not SQL NULL, including a present false/zero value. Does not impose parent=current-account or active=1 by default; the authenticated tenant table and TeamAccess predicate define visibility.
id is an integer. Ordinary columns retain database scalar/string/JSON-text representation. skills is a list of integer skill IDs and float multipliers, excluding zero multipliers; missing skills returns [].
No ORDER BY, pagination or server limit is applied. Omitted ids selects all eligible users; explicit [] returns []; malformed lists return invalid parameter: ids.
cost_per_hour is omitted without financial authority. Requested crm_access,permissions,app_permissions require explicit Users View and are otherwise omitted.

Side effects

Reads data without changing business records, edit markers, activity history or notifications. Shared setting reads can populate their normal settings cache.

See it in Fieldmotion

CRM1

Open Jobs Timeline, a user selector or the app stylesheet dialog in CRM1 and filter Users_list. Many callers filter active users in JavaScript after receiving them.

CRM2

CRM2 Kanban user filters and job availability loading call Users_list with active=1. The app stylesheet dialog also uses it.

Related endpoints

Users_getById — Fetch a selected, allowlisted projection after obtaining IDs.
Users_getDataTable — Compare CRM2’s mapped fields and table behavior.