Create a user role · Fieldmotion API

When to use this endpoint

Use UserRole_createData for the CRM2 Roles screen’s create workflow. Access fields are assigned in a subsequent request.

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 a caller without role state receives the create-permission error first.

Parameters

Parameter	Type	Required	Description
`name`	String	No at handler level	Role name. The CRM2 form requires it, but the server accepts omission/blank. Exact supplied duplicates return an error; there is no explicit length check before the 100-character database column.
`cDate`	Any	No	Ignored/replaced: the handler always sets the current server datetime before calling the generic creator.
`lastEdited`	Unix seconds or date text	No	Mapped Unix timestamp; numeric input is stored numerically and date text is passed through `strtotime`. Omission uses the current Unix time.
`id`	Any	No	Ignored during creation.

Example request

$created = FM_api('UserRole_createData', [
	'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 create role."}`	The add permission 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 server does not require a role name. Because cDate is injected, an empty request can insert an unnamed role. The shared uniqueness lookup also interpolates supplied names without escaping; integrations should use the validated CRM2 form or trusted normal names.

Unknown keys are ignored. The role map contains only ID, name, creation datetime, and Unix last-edited time.
The exact duplicate check follows the binary tenant collation. Case variants can be distinct.
No access rows or user assignments are created by this call.

Side effects

Inserts a user_roles row, invalidates the user-roles cache, and writes generic field-level creation history.
CRM2 normally follows this with UserRoleAccess_updateAccess to enable its default access field.

See it in Fieldmotion

CRM1

No direct CRM1 caller was found.

CRM2

Open Users → Roles and create a role. CRM2 first checks name uniqueness through the detail reader, calls this endpoint, then initializes access.

Related endpoints

UserRole_copy creates a role with copied access.
UserRoleAccess_updateAccess stores the role’s access fields.