Retrieve selected user-role fields

When to use this endpoint

Use UserRole_getRequestedDetails for role pickers, uniqueness checks, and the CRM2 role detail header. It returns a list even for one ID.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

Parameter	Type	Required	Description
`fields`	Native array	No	Any of `id`, `name`, `cDate`, and `lastEdited`. Omission requests all mapped fields.
`id / ids`	Integer string or native array	No	Optional role-ID filter. Scalars/array elements are integer-converted; JSON array text is not decoded.
`name / cDate / lastEdited`	Scalar or native array	No	Exact mapped filters. Text/datetime filters are case-insensitive; `lastEdited` is compared as integer Unix seconds.
`order`	Mapped name/object or native array	No	Optional mapped ordering, with exact `dir=desc` for descending.
`advanceSearch`	Native array	No	Shared advanced mapped conditions.

Example request

$roles = FM_api('UserRole_getRequestedDetails', [
	'id' => '12',
	'fields' => ['id', 'name', 'lastEdited'],
]);

Example response

[
  {"id": "12", "name": "Dispatch supervisor", "lastEdited": "2026-09-25 10:30:00"}
]

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 row matches the supplied ID/filters.
`Runtime warning or type error`	A shared array parameter is supplied in an unsupported scalar shape.

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

Behaviour and edge cases

No ID is required. Without filters, every role is returned, including the reserved ~Temporary User Role~.
lastEdited is stored as Unix seconds but rendered as a database datetime; cDate is already a datetime column.
There is no pagination, endpoint maximum, implicit ordering, or pageUserRoles_view permission check beyond authentication.

See it in Fieldmotion

CRM1

The legacy Users screen calls this route to resolve role IDs to names when roles are available.

CRM2

Users, availability, role lists, and the role detail screen use this reader for names/details and duplicate-name checks.

Related endpoints

UserRoles_getDataTable applies view permission, paging, and excludes the temporary role.
UserRoleAccess_getRequestedDetails reads access rows for a role.