Roles

Creates a custom role, like Roles → Create Role in the app.

Requires ManageRoles and an Idempotency-Key. The name must be unique in the organization (case-insensitive) and not a built-in role name; every permission must be a FlexPermissions name held by both the API key and its creator. Assign it to accounts with customRoleId / customRoleIds on /api/v1/users. Example: { "name": "Dispatcher", "description": "Schedules crews", "permissions": ["ViewJobs", "ManageJobs"] }.

post/api/v1/roles

Request

  • Base URL: https://app.flexonthejob.com
  • URL: https://app.flexonthejob.com/api/v1/roles
  • Auth: HTTP bearer

Request body

namestring nullable

Role name, 1..50 characters, unique in the organization and not a built-in role name. Example: "Dispatcher".

descriptionstring nullable

Free-text description, up to 200 characters.

permissionsstring[] nullable

FlexPermissions names the role grants (see get_org_capabilities / the permission catalog). Each must be held both by the API key and by the key's creator. Example: ["ViewJobs", "ManageJobs"].

Response

Created; Location points at the new role.

idinteger nullable

Custom role id (use it as customRoleId / in customRoleIds on the user endpoints); null for a built-in role. Example: 4.

namestring

Role name; for a built-in role this is the value to send as role. Example: "Manager".

descriptionstring

What the role is for. Example: "Manager with inventory and location management access".

isBuiltInboolean

True for OrganizationAdmin / Manager / User, which cannot be edited.

rankinteger

Hierarchy rank: OrganizationAdmin 3, Manager 2, User 1; custom roles 0 (they add permissions, not rank).

permissionsstring[]

Permissions the role grants, as FlexPermissions names. Example: ["ViewInventory", "ManageJobs"].

createdAtstring date-time nullable

UTC creation time (ISO-8601); null for built-in roles.

updatedAtstring date-time nullable

UTC last modification time (ISO-8601); null for built-in roles.

Changes

No recorded changes to this operation across all 1 revision of this API.