Copy a user role · Fieldmotion API

When to use this endpoint

Use UserRole_copy from CRM2’s Roles list when a new role should begin with an existing role’s access configuration.

Authentication and permissions

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

The permission check runs before the explicit login check, so an unauthenticated request normally receives the copy-permission error rather than not logged in.

Parameters

Parameter	Type	Required	Description
`id`	Integer string	Yes	Source role ID after integer conversion. Zero and nonexistent roles are not rejected.
`name`	String	Yes	New role name. Presence is required, but blank text is accepted if unique. Exact duplicates are rejected by the generic creator.

Example request

$copied = FM_api('UserRole_copy', [
	'id' => '7',
	'name' => 'Dispatch supervisor',
]);

Example response

{
  "ok": 1,
  "id": 12
}

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 copy role."}`	The role permission does not contain `pageUserRoles_add` or `all`.
`{"error":"missing or invalid parameter: id"}`	The `id` key is absent.
`{"error":"missing or invalid parameter: name"}`	The `name` key is absent.
`{"error":"Duplicate name"}`	A role with the exact supplied name already exists.

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

Behaviour and edge cases

The new role receives the server’s current creation datetime and Unix last_edited value.
Every source user_role_accesses.field value is copied with the new role ID and a current Unix last_edited. Access row IDs are newly generated.
No users are assigned to the copied role and no access-list/tenant-feature validation is applied.

Side effects

Inserts one user_roles row, invalidates its cache, and writes generic creation audit entries.
Bulk-inserts copied user_role_accesses rows without explicitly invalidating that cache or recalculating any user app_permissions bitmask.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

Open Users → Roles, choose Copy on a role, enter a name, and confirm. CRM2 calls this route and redraws the table.

Related endpoints

UserRole_createData creates a role without copying access.
UserRoleAccess_updateAccess replaces access and rebuilds the user bitmask.