Delete a user role · Fieldmotion API

When to use this endpoint

Use UserRole_deleteData only for roles with no assigned users. CRM2 runs a client-side check as well, but the server repeats it.

Authentication and permissions

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

The permission check occurs before login validation.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Role ID. Presence is required; zero/negative/non-numeric values are converted and can produce a successful no-op.
`name / cDate / lastEdited`	Mapped scalar	No	Additional supplied mapped values become extra `AND` deletion filters. Avoid them unless an intentional compare-and-delete is required.

Example request

$result = FM_api('UserRole_deleteData', [
	'id' => '12',
]);

Example response

{
  "ok": 1
}

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 delete role."}`	The delete permission is absent.
`{"error":"missing parameter: id"}`	The `id` key is absent.
`{"error":"Only roles with no user can be deleted. Please change the role of user or delete user connected to this role."}`	At least one tenant user has the converted role ID.
`{"ok":1}`	The role does not exist or optional extra filters do not match; affected-row count is not reported.

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

Behaviour and edge cases

Access rows are left orphaned. The role is hard-deleted, but user_role_accesses rows with the same role_id are not removed. Reusing that numeric ID later could expose stale access unless cleaned separately.

The user-reference check uses only the integer-converted id. The subsequent generic deletion uses every supplied mapped field as an exact filter.
The route accepts only a scalar safely; a native ID array reaches intval before the generic helper can use its bulk-filter support.
There is no soft-delete or restore path for user roles.

Side effects

Hard-deletes matching user_roles rows and invalidates that cache.
When a row was found, writes tenant deletion-log data and a generic delete audit event. It does not change access rows or users.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

Open Users → Roles, select unused roles, and choose Delete. CRM2 checks assignments, confirms, then calls this endpoint once per ID.

Related endpoints

UserRole_getRequestedDetails can verify a role before deletion.
UserRoleAccess_getRequestedDetails exposes access rows that this route does not clean up.