Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/SoftwareVerse/userverse/llms.txt

Use this file to discover all available pages before exploring further.

All endpoints require a valid JWT Bearer token in the Authorization header. Each company is automatically provisioned with two system roles when it is created: Administrator (full access to manage users and data) and Viewer (read-only access to company data). Default roles cannot be deleted.

​
Create a role

Creates a new custom role for the specified company. 
POST /company/{company_id}/role

​
Path parameters

​
company_id
integer
required
The unique identifier of the company the role belongs to.

​
Request body

​
name
string
required
Name of the new role. Must be unique within the company.
​
description
string
A human-readable description of the role’s permissions or purpose.

​
Response fields

​
message
string
Human-readable confirmation message.
​
data
object
The newly created role.

​
Error codes

StatusDescription
400A role with the same name already exists in this company, or the request body is invalid.
500An unexpected server error occurred.

​
Example

curl --request POST \
  --url https://api.example.com/company/42/role \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Billing Manager",
    "description": "Can view and manage billing information."
  }'

​
Update a role

Updates the name or description of an existing role identified by its current name. 
PATCH /company/{company_id}/role/{name}

​
Path parameters

​
company_id
integer
required
The ID of the company the role belongs to.
​
name
string
required
The current name of the role to update.

​
Request body

​
name
string
New name for the role.
​
description
string
Updated description for the role.

​
Response fields

​
message
string
Human-readable confirmation message.
​
data
object
The updated role.

​
Error codes

StatusDescription
400The request body is invalid.
404No role with the given name was found for this company.
500An unexpected server error occurred.

​
Example

curl --request PATCH \
  --url 'https://api.example.com/company/42/role/Billing%20Manager' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Finance Manager",
    "description": "Can view and manage all financial records."
  }'

​
Delete a role

Deletes a custom role from a company. All users currently assigned the deleted role are automatically reassigned to the specified replacement role. 
DELETE /company/{company_id}/role
Default system roles (Administrator and Viewer) cannot be deleted. Attempting to do so will return a 400 error.

​
Path parameters

​
company_id
integer
required
The ID of the company to delete the role from.

​
Request body

​
role_name_to_delete
string
required
Name of the role to delete. Cannot be a default system role.
​
replacement_role_name
string
required
Name of the role that affected users will be reassigned to after deletion.

​
Response fields

​
message
string
Human-readable confirmation message.
​
data
object
A result summary object. The exact shape is determined at runtime and may include details about reassigned users.

​
Error codes

StatusDescription
400role_name_to_delete is a default system role, or the request body is invalid.
404The role to delete or the replacement role was not found.
500An unexpected server error occurred.

​
Example

curl --request DELETE \
  --url https://api.example.com/company/42/role \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "role_name_to_delete": "Finance Manager",
    "replacement_role_name": "Viewer"
  }'

​
List roles

Returns a paginated list of all roles associated with a company. Supports filtering by name and description. 
GET /company/{company_id}/roles

​
Path parameters

​
company_id
integer
required
The ID of the company whose roles you want to retrieve.

​
Query parameters

​
page
integer
default:"1"
Page number to retrieve. Must be 1 or greater.
​
limit
integer
default:"10"
Number of records per page. Accepted range: 1–100.
​
name
string
Filter results to roles whose name matches this value.
​
description
string
Filter results to roles whose description matches this value.

​
Response fields

​
message
string
Human-readable confirmation message.
​
data
object
Paginated response wrapper.

​
Error codes

StatusDescription
400The request contains invalid query parameters.
500An unexpected server error occurred.

​
Example

curl --request GET \
  --url 'https://api.example.com/company/42/roles?page=1&limit=10&name=Admin' \
  --header 'Authorization: Bearer <token>'

Build docs developers (and LLMs) love

Get started for freeTalk to us