Skip to content
4HSE

Role

Manage roles, which represent office or project roles assigned to people.
You can create, update, delete, and search for roles with advanced filtering and pagination.

Version
2.0.0
OpenAPI version
3.0.0

Operations

Section titled “Operations”

index

Section titled “index”
POST
/v2/role/index

Returns a paginated and filterable list of roles.
Use POST to allow complex filters via JSON payload.

Request Body

Section titled “Request Body ”

Parameters for searching roles

object
filter
object
office_role_id

The unique identifier of the office role.

string format: uuid
office_id

The unique identifier of the office associated with the role.

string format: uuid
code

The code associated with the office role, if available.

string
nullable
name

The name of the office role.

string
description

A description of the office role, if available.

string
nullable
project_id

The unique identifier of the associated project.

string format: uuid
project_name

The name of the associated project.

string
project_type

The type of the associated project.

string
office_name

The name of the associated office.

string
owned_active

Indicates whether the office role is actively owned.

boolean
parent_active

Indicates whether the parent office role is active.

boolean
per-page
integer
default: 100 >= 1
page
integer
default: 1 >= 1
sort

The field of the model to sort the list for, use a minus to revert the sort. Es -name is to require the sort in reverse order

string
history

The field establishes whether to also include historized elements that are no longer active in the results. If you leave this parameter empty the response returns only actual entries.

boolean
Example
{
  "filter": {
    "name": "Manager",
    "office_id": "off-1"
  },
  "per-page": 10,
  "page": 1,
  "sort": "name"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

List of roles

Array<object>
object
office_role_id

The unique identifier of the office role.

string format: uuid
office_id

The unique identifier of the office associated with the role.

string format: uuid
code

The code associated with the office role, if available.

string
nullable
name

The name of the office role.

string
description

A description of the office role, if available.

string
nullable
project_id

The unique identifier of the associated project.

string format: uuid
project_name

The name of the associated project.

string
project_type

The type of the associated project.

string
office_name

The name of the associated office.

string
owned_active

Indicates whether the office role is actively owned.

boolean
parent_active

Indicates whether the parent office role is active.

boolean
Example
{
  "office_role_id": "role-1",
  "office_id": "off-1",
  "code": "MGR",
  "name": "Manager",
  "description": "Manages the office",
  "project_id": "proj-1"
}

Headers

Section titled “Headers ”
X-Pagination-Current-Page
integer

Current page

X-Pagination-Page-Count
integer

Total number of pages

X-Pagination-Per-Page
integer

Number of items per page

X-Pagination-Total-Count
integer

Total number of items

create

Section titled “create”
POST
/v2/role/create

Create a new role by providing the required details.

Request Body required

Section titled “Request Body required ”

Role object to be created

object
office_role_id

The unique identifier of the office role.

string
office_id

The unique identifier of the office associated with the role.

string
code

The code associated with the office role, if available.

string
nullable
name

The name of the office role.

string
description

A description of the office role, if available.

string
nullable
project_id

The unique identifier of the associated project.

string
Example
{
  "office_id": "off-2",
  "code": "ENG",
  "name": "Engineer",
  "description": "Responsible for technical tasks",
  "project_id": "proj-2"
}

Responses

Section titled “ Responses ”
201
Section titled “201 ”

Role created successfully

object
office_role_id

The unique identifier of the office role.

string
office_id

The unique identifier of the office associated with the role.

string
code

The code associated with the office role, if available.

string
nullable
name

The name of the office role.

string
description

A description of the office role, if available.

string
nullable
project_id

The unique identifier of the associated project.

string
Example
{
  "office_role_id": "role-2",
  "office_id": "off-2",
  "code": "ENG",
  "name": "Engineer",
  "description": "Responsible for technical tasks",
  "project_id": "proj-2"
}

view

Section titled “view”
GET
/v2/role/view/{id}

Retrieve a role by its unique ID.

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

ID of the role to retrieve

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Role found

object
office_role_id

The unique identifier of the office role.

string format: uuid
office_id

The unique identifier of the office associated with the role.

string format: uuid
code

The code associated with the office role, if available.

string
nullable
name

The name of the office role.

string
description

A description of the office role, if available.

string
nullable
project_id

The unique identifier of the associated project.

string format: uuid
project_name

The name of the associated project.

string
project_type

The type of the associated project.

string
office_name

The name of the associated office.

string
owned_active

Indicates whether the office role is actively owned.

boolean
parent_active

Indicates whether the parent office role is active.

boolean
Example
{
  "office_role_id": "role-1",
  "office_id": "off-1",
  "code": "MGR",
  "name": "Manager",
  "description": "Manages the office",
  "project_id": "proj-1"
}
404
Section titled “404 ”

Role not found

delete

Section titled “delete”
DELETE
/v2/role/delete/{id}

Delete a role by its unique ID.
If force=true, all related entities will also be deleted.

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

ID of the role to delete

Query Parameters

Section titled “Query Parameters ”
force
boolean

Force the deletion of the entity and all related entities

Responses

Section titled “ Responses ”
204
Section titled “204 ”

Role deleted successfully

400
Section titled “400 ”

If force=false, the operation is interrupted and the list of connected entities that will be deleted in case of confirmation (force=true) is returned

update

Section titled “update”
PUT
/v2/role/update/{id}

Update an existing role by its unique ID.

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

ID of the role to update

Request Body required

Section titled “Request Body required ”

Role object with updated data

object
office_role_id

The unique identifier of the office role.

string
office_id

The unique identifier of the office associated with the role.

string
code

The code associated with the office role, if available.

string
nullable
name

The name of the office role.

string
description

A description of the office role, if available.

string
nullable
project_id

The unique identifier of the associated project.

string
Example
{
  "name": "Updated Manager",
  "description": "Updated description"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Role updated successfully

object
office_role_id

The unique identifier of the office role.

string
office_id

The unique identifier of the office associated with the role.

string
code

The code associated with the office role, if available.

string
nullable
name

The name of the office role.

string
description

A description of the office role, if available.

string
nullable
project_id

The unique identifier of the associated project.

string
Example
{
  "office_role_id": "role-1",
  "name": "Updated Manager",
  "description": "Updated description"
}
404
Section titled “404 ”

Role not found