Retrieve selected users by ID

When to use this endpoint

Use after another call supplies IDs, especially for export labels. Unlike User_get it does not select the whole row.

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
`ids`	JSON list or native list	Yes	Flat positive integer IDs or digit strings. Explicit [] returns []; malformed lists return invalid parameter: ids. Omitted/null is a missing-parameter error.
`fields`	Native or JSON-encoded list	No	Optional flat native/JSON string list. Unknown or unauthorised fields are ignored; a projection with no permitted fields returns no fields selected. Financial fields require elevated authority.

Example request

$result = FM_api('Users_getById', [
	'ids'=>json_encode(['1042', '1088']),
	'fields'=>['id', 'name', 'worker_id'],
]);

Example response

[
  {
    "id": "1042",
    "name": "Alex Morgan",
    "worker_id": "ENG-1042"
  }
]

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: ids"}`	ids is absent/null.
`{"error": "no fields selected"}`	Present fields contains no permitted field.
`{"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

Only requested/default allowlisted fields are selected; id is not automatically added when a custom projection omits it. Worker ID is extracted from meta.worker_id as text.
Financial fields are available only when requested and financially authorised, not by default. No active, temporary or parent-membership filter is added beyond the tenant table and row scope.
The dispatcher checks explicit IDs for configured TeamAccess scope. SQL does not preserve input order; absent IDs are omitted, not returned as null placeholders. No pagination/limit is applied.
Scalar types remain database values, including string IDs; this differs from Users_list’s integer id.

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

CRM1 export widgets call Users_getById to resolve user names, worker IDs and admin financial fields before producing CSV.

CRM2

CRM2’s User object cache and export widgets use Users_getById; exports request id/name/worker_id.

Related endpoints

Users_list — Read the basic selectable user list and its explicit scope predicate.
User_get — Inspect the older complete user-row contract.