Skip to content
4HSE Developers DEV

Office

An Office represents a work location, construction site, or operational unit within a project (company). It is the middle level in the hierarchy: Project (company) → Office (work location) → Person (worker).

Other APIs reference the office via the subtenant_id field — pass the office_id.

Use this API to:

  • Find work locations within a company (filter by project_id)
  • Get the office_id needed before creating actions, checking the compliance schedule, or managing personnel
  • Look up work location details (address, type, associated personnel)

Actions and the compliance schedule (ActionSubscription) are directly linked to an office. People are assigned to offices via PersonOffice.

When an office is no longer active (historicized), all its child entities (person assignments, actions, compliance schedule entries, etc.) are automatically excluded from normal queries without any direct changes to their data. The parent_active field in child entity responses reflects this state. Use the history: true parameter in the index to include inactive offices.

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/office/index

Returns a paginated list of offices.

Most useful filters:

  • project_id: find all offices within a company (most common use)
  • name: search an office by name within a project
  • office_type_icon: filter by type (e.g. construction_site for construction sites)

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

Parameters for searching offices

object
filter
object
office_id

Unique identifier of the office. Other APIs reference the office via the subtenant_id field — pass this value.

string format: uuid
project_id

The project (company) this office belongs to.

string format: uuid
name

Name of the office or work location.

string
description

Optional free-text description.

string
street

Street address.

string
postal_code

Postal code.

string
region

Region or province code.

string
locality

City or locality.

string
country

ISO 3166-1 alpha-2 country code.

string
tax_code

Tax code of the work location.

string
vat

VAT number of the work location.

string
office_type_id

Custom office type identifier.

string format: uuid
created_at

Creation timestamp.

integer
updated_at

Last modification timestamp.

integer
code

Alternative identifier code for the office.

string
office_type_icon

Visual type of the office:

  • office_default: a standard office or headquarters
  • construction_site: a construction site
string
Allowed values: office_default construction_site
project_name

Name of the project (company) this office belongs to.

string
project_type

Type of the parent project.

string
Allowed values: safety template
project_status

Status of the parent project.

string
Allowed values: active suspended pending_delete deleted
owned_active

Whether this office is currently active in its validity period.

boolean
nullable
parent_active

Whether the parent project is currently active.

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

Field to sort by. Prefix with minus for descending order (e.g. “-name”).

string
Allowed values: name code
history

If true, includes historized (no longer active) entries in the results. By default only current entries are returned.

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

Responses

Section titled “ Responses ”
200
Section titled “200 ”

List of offices

Array<object>
object
office_id

Unique identifier of the office. Other APIs reference the office via the subtenant_id field — pass this value.

string format: uuid
project_id

The project (company) this office belongs to.

string format: uuid
name

Name of the office or work location.

string
description

Optional free-text description.

string
street

Street address.

string
postal_code

Postal code.

string
region

Region or province code.

string
locality

City or locality.

string
country

ISO 3166-1 alpha-2 country code.

string
tax_code

Tax code of the work location.

string
vat

VAT number of the work location.

string
office_type_id

Custom office type identifier.

string format: uuid
created_at

Creation timestamp.

integer
updated_at

Last modification timestamp.

integer
code

Alternative identifier code for the office.

string
office_type_icon

Visual type of the office:

  • office_default: a standard office or headquarters
  • construction_site: a construction site
string
Allowed values: office_default construction_site
project_name

Name of the project (company) this office belongs to.

string
project_type

Type of the parent project.

string
Allowed values: safety template
project_status

Status of the parent project.

string
Allowed values: active suspended pending_delete deleted
owned_active

Whether this office is currently active in its validity period.

boolean
nullable
parent_active

Whether the parent project is currently active.

boolean
nullable
Example
[
  {
    "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Rome North Site",
    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
    "code": "RN-001",
    "office_type_icon": "construction_site",
    "street": "123 Main Road",
    "locality": "Rome",
    "postal_code": "00198",
    "region": "RM",
    "country": "IT",
    "project_name": "Acme Construction Ltd",
    "project_type": "safety",
    "project_status": "active",
    "owned_active": true,
    "parent_active": true,
    "created_at": 1700000000,
    "updated_at": 1700000001
  }
]

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/office/create

Creates a new office within a project.

Requires project_id and name. The office_id is auto-generated if not provided. The name must be unique within the project.

After creation, the folder structure for file storage is prepared automatically. The typical next step is to assign people to the office via the PersonOffice API.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Office object to be created

object
office_id

Unique identifier of the office. Auto-generated if not provided on creation. Other APIs reference the office via the subtenant_id field — pass this value. If unknown, use the index endpoint filtering by project_id and name to find it.

string format: uuid
project_id
required

The project (company) this office belongs to. Pass the project_id obtained from the Project API.

string format: uuid
name
required

Name of the office or work location. Must be unique within the project.

string
<= 255 characters
description

Optional free-text description.

string
street

Street address.

string
<= 255 characters
postal_code

Postal code.

string
<= 50 characters
region

Region or province code.

string
<= 10 characters
locality

City or locality.

string
<= 50 characters
country

ISO 3166-1 alpha-2 country code.

string
<= 20 characters
tax_code

Tax code of the work location.

string
<= 20 characters
vat

VAT number of the work location.

string
<= 20 characters
office_type_id

Custom office type identifier.

string format: uuid
created_at

Creation timestamp.

integer
updated_at

Last modification timestamp.

integer
code

Alternative identifier code for the office.

string
<= 50 characters
office_type_icon

Visual type of the office:

  • office_default: a standard office or headquarters
  • construction_site: a construction site
string
<= 150 characters
Allowed values: office_default construction_site
Example
{
  "name": "Rome North Site",
  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "code": "RN-001",
  "office_type_icon": "construction_site",
  "street": "123 Main Road",
  "locality": "Rome",
  "postal_code": "00198",
  "region": "RM",
  "country": "IT"
}

Responses

Section titled “ Responses ”
201
Section titled “201 ”

Office created successfully

object
office_id

Unique identifier of the office. Auto-generated if not provided on creation. Other APIs reference the office via the subtenant_id field — pass this value. If unknown, use the index endpoint filtering by project_id and name to find it.

string format: uuid
project_id
required

The project (company) this office belongs to. Pass the project_id obtained from the Project API.

string format: uuid
name
required

Name of the office or work location. Must be unique within the project.

string
<= 255 characters
description

Optional free-text description.

string
street

Street address.

string
<= 255 characters
postal_code

Postal code.

string
<= 50 characters
region

Region or province code.

string
<= 10 characters
locality

City or locality.

string
<= 50 characters
country

ISO 3166-1 alpha-2 country code.

string
<= 20 characters
tax_code

Tax code of the work location.

string
<= 20 characters
vat

VAT number of the work location.

string
<= 20 characters
office_type_id

Custom office type identifier.

string format: uuid
created_at

Creation timestamp.

integer
updated_at

Last modification timestamp.

integer
code

Alternative identifier code for the office.

string
<= 50 characters
office_type_icon

Visual type of the office:

  • office_default: a standard office or headquarters
  • construction_site: a construction site
string
<= 150 characters
Allowed values: office_default construction_site
Example
{
  "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Rome North Site",
  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "code": "RN-001",
  "office_type_icon": "construction_site",
  "street": "123 Main Road",
  "locality": "Rome",
  "postal_code": "00198",
  "region": "RM",
  "country": "IT",
  "created_at": 1700000000,
  "updated_at": 1700000000
}

view

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

Retrieves a single office by its ID.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The office_id to retrieve.

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Office found

object
office_id

Unique identifier of the office. Other APIs reference the office via the subtenant_id field — pass this value.

string format: uuid
project_id

The project (company) this office belongs to.

string format: uuid
name

Name of the office or work location.

string
description

Optional free-text description.

string
street

Street address.

string
postal_code

Postal code.

string
region

Region or province code.

string
locality

City or locality.

string
country

ISO 3166-1 alpha-2 country code.

string
tax_code

Tax code of the work location.

string
vat

VAT number of the work location.

string
office_type_id

Custom office type identifier.

string format: uuid
created_at

Creation timestamp.

integer
updated_at

Last modification timestamp.

integer
code

Alternative identifier code for the office.

string
office_type_icon

Visual type of the office:

  • office_default: a standard office or headquarters
  • construction_site: a construction site
string
Allowed values: office_default construction_site
project_name

Name of the project (company) this office belongs to.

string
project_type

Type of the parent project.

string
Allowed values: safety template
project_status

Status of the parent project.

string
Allowed values: active suspended pending_delete deleted
owned_active

Whether this office is currently active in its validity period.

boolean
nullable
parent_active

Whether the parent project is currently active.

boolean
nullable
Example
{
  "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Rome North Site",
  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "code": "RN-001",
  "office_type_icon": "construction_site",
  "street": "123 Main Road",
  "locality": "Rome",
  "postal_code": "00198",
  "region": "RM",
  "country": "IT",
  "project_name": "Acme Construction Ltd",
  "project_type": "safety",
  "project_status": "active",
  "owned_active": true,
  "parent_active": true,
  "created_at": 1700000000,
  "updated_at": 1700000001
}
404
Section titled “404 ”

Office not found

update

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

Updates an existing office.

Common use cases: changing the name, updating the address, changing the office type. The name must remain unique within the project.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The office_id to update.

Request Body required

Section titled “Request Body required ”

Office fields to update

object
office_id

Unique identifier of the office. Auto-generated if not provided on creation. Other APIs reference the office via the subtenant_id field — pass this value. If unknown, use the index endpoint filtering by project_id and name to find it.

string format: uuid
project_id
required

The project (company) this office belongs to. Pass the project_id obtained from the Project API.

string format: uuid
name
required

Name of the office or work location. Must be unique within the project.

string
<= 255 characters
description

Optional free-text description.

string
street

Street address.

string
<= 255 characters
postal_code

Postal code.

string
<= 50 characters
region

Region or province code.

string
<= 10 characters
locality

City or locality.

string
<= 50 characters
country

ISO 3166-1 alpha-2 country code.

string
<= 20 characters
tax_code

Tax code of the work location.

string
<= 20 characters
vat

VAT number of the work location.

string
<= 20 characters
office_type_id

Custom office type identifier.

string format: uuid
created_at

Creation timestamp.

integer
updated_at

Last modification timestamp.

integer
code

Alternative identifier code for the office.

string
<= 50 characters
office_type_icon

Visual type of the office:

  • office_default: a standard office or headquarters
  • construction_site: a construction site
string
<= 150 characters
Allowed values: office_default construction_site
Example
{
  "name": "Rome South Site",
  "street": "456 New Road"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Office updated successfully

object
office_id

Unique identifier of the office. Auto-generated if not provided on creation. Other APIs reference the office via the subtenant_id field — pass this value. If unknown, use the index endpoint filtering by project_id and name to find it.

string format: uuid
project_id
required

The project (company) this office belongs to. Pass the project_id obtained from the Project API.

string format: uuid
name
required

Name of the office or work location. Must be unique within the project.

string
<= 255 characters
description

Optional free-text description.

string
street

Street address.

string
<= 255 characters
postal_code

Postal code.

string
<= 50 characters
region

Region or province code.

string
<= 10 characters
locality

City or locality.

string
<= 50 characters
country

ISO 3166-1 alpha-2 country code.

string
<= 20 characters
tax_code

Tax code of the work location.

string
<= 20 characters
vat

VAT number of the work location.

string
<= 20 characters
office_type_id

Custom office type identifier.

string format: uuid
created_at

Creation timestamp.

integer
updated_at

Last modification timestamp.

integer
code

Alternative identifier code for the office.

string
<= 50 characters
office_type_icon

Visual type of the office:

  • office_default: a standard office or headquarters
  • construction_site: a construction site
string
<= 150 characters
Allowed values: office_default construction_site
Example
{
  "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Rome South Site",
  "street": "456 New Road"
}
404
Section titled “404 ”

Office not found

delete

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

Deletes an office.

If force=false (default), the operation is interrupted and the response lists all child entities (person assignments, actions, compliance schedule entries, etc.) that would be deleted. If force=true, the office and all related entities are deleted.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The office_id to delete.

Query Parameters

Section titled “Query Parameters ”
force
boolean

If true, deletes the office and all child entities. If false, returns a preview of the entities that would be affected.

Responses

Section titled “ Responses ”
204
Section titled “204 ”

Office deleted successfully

400
Section titled “400 ”

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