---
title: "Office"
url: "https://dev.4hse.com/api/office"
---

# 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 ”](#authentication)

### OAuth2

[Section titled “OAuth2 ”](#oauth2)

**Security scheme type:** oauth2

**Flow type:** password

**Token URL:** [https://auth.4hse.com/realms/4hse/protocol/openid-connect/token](https://auth.4hse.com/realms/4hse/protocol/openid-connect/token)

### AccessToken

[Section titled “AccessToken ”](#accesstoken)

**Security scheme type:** apiKey

**Query parameter name:** access-token

## Operations

[Section titled “Operations”](#operations)

### index

[Section titled “index”](#operation-indexOffice-post)

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 ”](#authorizations)

-   **[OAuth2](/api/office/#oauth2)**
-   **[AccessToken](/api/office/#accesstoken)**

#### Request Body

[Section titled “Request Body ”](#request-body)

Parameters for searching offices

Select media typeapplication/json

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 ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of offices

Select media typeapplication/json

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 ”](#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”](#operation-createOffice-post)

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 ”](#authorizations)

-   **[OAuth2](/api/office/#oauth2)**
-   **[AccessToken](/api/office/#accesstoken)**

#### Request Body required

[Section titled “Request Body required ”](#request-body)

Office object to be created

Select media typeapplication/json

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 ”](#responses)

##### 201

[Section titled “201 ”](#201)

Office created successfully

Select media typeapplication/json

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”](#operation-viewOffice-get)

GET

/v2/office/view/{id}

-   

Retrieves a single office by its ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

-   **[OAuth2](/api/office/#oauth2)**
-   **[AccessToken](/api/office/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

The office\_id to retrieve.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Office found

Select media typeapplication/json

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 ”](#404)

Office not found

### update

[Section titled “update”](#operation-updateOffice-put)

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 ”](#authorizations)

-   **[OAuth2](/api/office/#oauth2)**
-   **[AccessToken](/api/office/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

The office\_id to update.

#### Request Body required

[Section titled “Request Body required ”](#request-body)

Office fields to update

Select media typeapplication/json

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 ”](#responses)

##### 200

[Section titled “200 ”](#200)

Office updated successfully

Select media typeapplication/json

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 ”](#404)

Office not found

### delete

[Section titled “delete”](#operation-deleteOffice-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 ”](#authorizations)

-   **[OAuth2](/api/office/#oauth2)**
-   **[AccessToken](/api/office/#accesstoken)**

#### Path Parameters

[Section titled “Path Parameters ”](#path-parameters)

**id**

required

string format: uuid

The office\_id to delete.

#### Query Parameters

[Section titled “Query Parameters ”](#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 ”](#responses)

##### 204

[Section titled “204 ”](#204)

Office deleted successfully

##### 400

[Section titled “400 ”](#400)

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

This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.