Query user roles · Fieldmotion API

When to use this endpoint

Use UserRoles_getDataTable for CRM2’s Roles list. Use the detail reader for unpaged role lookups or when the reserved temporary role must remain visible.

Authentication and permissions

The authenticated context must contain pageUserRoles_view or the global all role permission.

The permission check runs before explicit login validation.

Parameters

Parameter	Type	Required	Description
`fields`	Native array	Yes	Mapped keys `id`, `name`, `cDate`, and `lastEdited`. Special pseudo-field `user` appends assigned names after querying; unknown fields are otherwise ignored.
`isTable / draw / start / length`	Integer strings	No	Shared table controls. Table mode defaults on with offset `0`, length `10`, and draw `0`. Exact `isTable=0` returns only data and supports a positive `limit`.
`orderBy / orderDesc / order`	Shared mapped ordering	No	Order by mapped role fields. The derived `user`
`searchValue / searchField`	String / mapped names	No	Case-insensitive substring search over mapped fields. `user`
`Mapped filters / advanceSearch / groupBy`	Shared scalar/array controls	No	Generic filters and grouping over mapped role fields.

Example request

$page = FM_api('UserRoles_getDataTable', [
	'fields' => ['id', 'name', 'user', 'cDate'],
	'start' => '0',
	'length' => '25',
	'draw' => '3',
]);

Example response

{
  "data": [
    {"id":"12","name":"Dispatch supervisor","cDate":"2026-09-25 10:00:00","user":"Alex Byrne, Sam Lee"}
  ],
  "draw": 3,
  "recordsTotal": "6",
  "recordsFiltered": "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":"You do not have the correct permissions to view roles."}`	The view permission is absent.
`{"error":"missing or invalid parameter: fields"}`	`fields` is absent.
`{"error":"error in database query"}`	The generated mapped query fails.

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

Behaviour and edge cases

Total and filtered counts intentionally differ. The data/filter query excludes exact name ~Temporary User Role~, but recordsTotal counts every role. Even with no user filter, the total can therefore exceed recordsFiltered by one.

When user is requested, all tenant users are loaded without active/non-login filtering and grouped by role_id; names are joined with comma-space in database row order.
lastEdited is converted from Unix seconds to a datetime string. The reserved-role exclusion is exact and case-sensitive under the binary collation.
The derived user

See it in Fieldmotion

CRM1

CRM1 does not use this CRM2 table route.

CRM2

Open Users → Roles. The shared table requests mapped columns plus the derived Users display.

Related endpoints

UserRole_getRequestedDetails provides unpaged mapped lookups without excluding the temporary role.
UserRoleAccess_getRequestedDetails lists access fields for a role.