Create a BusinessRole

Create a new role for a business.

Permission Hierarchy Validation: Permissions follow a hierarchy structure where category permissions (e.g., payments.manage) must be enabled before their extended permissions (e.g., payments.invoices.export) can be used. Extended permissions have three parts in their key (e.g., category.subcategory.action), while category permissions have two parts (e.g., category.manage). If you attempt to enable an extended permission without its corresponding category permission, the API will return a 400 error.

Available for Staff Tokens

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required

A unique readable code for the role. Must be unique across all business roles. Common codes like 'admin', 'owner', 'staff', 'manager' typically already exist as default system roles. Use a unique code (e.g., 'custom_role_123') to avoid conflicts.

string
required

The role name as it's presented in the UI. By default, it will be assigned from the original permission, but can be overridden for a specific business

string
required

The role description as it’s presented in the UI. By default, it will be assigned from the original permission, but can be overridden for a specific business

permissions
array of objects
required

A list of permissions that are assigned to the role by default

permissions*
boolean
Defaults to true

A flag to indicate if the role can be edited by the business. By default, system roles are not editable. Can not be changed after creation

Responses

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json