Skip to content
4HSE Developers DEV

OrgUnit

An OrgUnit represents a unit in the company organization chart. Organization units have a tree structure: each unit can have a parent unit (parent_org_unit_id) and multiple child units.

Examples: “General Management”, “Production Department”, “Quality Office”.

Belongs to a project (not to an office). People are assigned to organization units via OrgPerson, optionally with a role (OrgRole).

Use this API to:

  • Define the company organization chart structure
  • Create child units (by passing parent_org_unit_id)
  • Browse the organization chart for a project (filter by project_id)

Supports historicization.

Version
2.0.0
OpenAPI version
3.0.0

Authentication

Section titled “ Authentication ”

OAuth2

Section titled “OAuth2 ”

Security scheme type: oauth2

Flow type: password

Token URL: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token

AccessToken

Section titled “AccessToken ”

Security scheme type: apiKey

Query parameter name: access-token

Operations

Section titled “Operations”

index

Section titled “index”
POST
/v2/org-unit/index

Returns a paginated list of organization units.

Most useful filters:

  • project_id: all units in a company
  • parent_org_unit_id: child units of a specific unit
  • name: search by name

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

Parameters for searching

object
filter
object
org_unit_id
string format: uuid
code
string
name
string
description
string
parent_org_unit_id
string format: uuid
nullable
project_id
string format: uuid
owned_active

Whether this unit is currently active.

boolean
nullable
parent_active

Whether the parent entities are currently active.

boolean
nullable
per-page
integer
default: 100 >= 1
page
integer
default: 1 >= 1
sort
string
Allowed values: code name
history

If true, includes historicized entries.

boolean
Example
{
  "filter": {
    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"
  },
  "per-page": 20,
  "page": 1,
  "sort": "name"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

List of organization units

Array<object>
object
org_unit_id
string format: uuid
code
string
name
string
description
string
parent_org_unit_id
string format: uuid
nullable
project_id
string format: uuid
owned_active

Whether this unit is currently active.

boolean
nullable
parent_active

Whether the parent entities are currently active.

boolean
nullable

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/org-unit/create

Creates a new organization unit.

Requires name and project_id. The org_unit_id is auto-generated if not provided.

To create a child unit, pass the parent_org_unit_id of the parent unit. Omit parent_org_unit_id for top-level units.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Organization unit to create

object
org_unit_id

Unique identifier. Auto-generated if not provided.

string format: uuid
code

Identifier code.

string
<= 50 characters
name
required

Name of the organization unit.

string
<= 255 characters
description

Optional description.

string
nullable
parent_org_unit_id

Parent unit in the tree hierarchy. Null for top-level units. Pass the org_unit_id of the parent.

string format: uuid
nullable
project_id
required

The project (company). Pass the project_id.

string format: uuid

Responses

Section titled “ Responses ”
201
Section titled “201 ”

Organization unit created successfully

object
org_unit_id

Unique identifier. Auto-generated if not provided.

string format: uuid
code

Identifier code.

string
<= 50 characters
name
required

Name of the organization unit.

string
<= 255 characters
description

Optional description.

string
nullable
parent_org_unit_id

Parent unit in the tree hierarchy. Null for top-level units. Pass the org_unit_id of the parent.

string format: uuid
nullable
project_id
required

The project (company). Pass the project_id.

string format: uuid

view

Section titled “view”
GET
/v2/org-unit/view/{id}

Retrieves a single organization unit by its ID.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The org_unit_id to retrieve.

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Organization unit found

object
org_unit_id
string format: uuid
code
string
name
string
description
string
parent_org_unit_id
string format: uuid
nullable
project_id
string format: uuid
owned_active

Whether this unit is currently active.

boolean
nullable
parent_active

Whether the parent entities are currently active.

boolean
nullable
404
Section titled “404 ”

Not found

update

Section titled “update”
PUT
/v2/org-unit/update/{id}

Updates an existing organization unit.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The org_unit_id to update.

Request Body required

Section titled “Request Body required ”

Fields to update

object
org_unit_id

Unique identifier. Auto-generated if not provided.

string format: uuid
code

Identifier code.

string
<= 50 characters
name
required

Name of the organization unit.

string
<= 255 characters
description

Optional description.

string
nullable
parent_org_unit_id

Parent unit in the tree hierarchy. Null for top-level units. Pass the org_unit_id of the parent.

string format: uuid
nullable
project_id
required

The project (company). Pass the project_id.

string format: uuid

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Updated successfully

object
org_unit_id

Unique identifier. Auto-generated if not provided.

string format: uuid
code

Identifier code.

string
<= 50 characters
name
required

Name of the organization unit.

string
<= 255 characters
description

Optional description.

string
nullable
parent_org_unit_id

Parent unit in the tree hierarchy. Null for top-level units. Pass the org_unit_id of the parent.

string format: uuid
nullable
project_id
required

The project (company). Pass the project_id.

string format: uuid
404
Section titled “404 ”

Not found

delete

Section titled “delete”
DELETE
/v2/org-unit/delete/{id}

Deletes an organization unit.

If force=false (default), the response lists child entities (child units, person assignments). If force=true, the unit and all child entities are deleted.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The org_unit_id to delete.

Query Parameters

Section titled “Query Parameters ”
force
boolean

If true, deletes the unit and all child entities.

Responses

Section titled “ Responses ”
204
Section titled “204 ”

Deleted successfully

400
Section titled “400 ”

Preview of entities that would be deleted (returned when force=false)