---
title: "PersonOffice"
url: "https://dev.4hse.com/api/personoffice"
---

# PersonOffice

A **PersonOffice** represents the assignment of a person to an office. It is the entity that links a person (worker) to a work location within the same project.

A person can be assigned to multiple offices, and an office can have multiple people assigned to it.

Use this API to:

-   Assign a person to an office after creating them
-   Find all people assigned to an office (filter by `office_id`)
-   Find all offices a person is assigned to (filter by `person_id`)
-   Look up personal details in the context of their office assignment

The index and view responses include the person’s details and office information, providing a complete view without additional calls.

When a PersonOffice is historicized, its child entities (work groups, etc.) are automatically excluded from normal queries. The `parent_active` field reflects this state.

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-indexPersonOffice-post)

POST

/v2/person-office/index

-   

Returns a paginated list of person-office assignments.

Most useful filters:

-   `office_id`: all people assigned to a specific office
-   `person_id`: all offices a person is assigned to
-   `person_last_name` + `office_id`: find a person by last name in a specific office
-   `person_tax_code`: find by tax code

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body

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

Parameters for searching person-office assignments

Select media typeapplication/json

object

**filter**

object

**person\_office\_id**

Unique identifier of the assignment.

string format: uuid

**office\_id**

The office the person is assigned to.

string format: uuid

**person\_id**

The assigned person.

string format: uuid

**project\_id**

The project this assignment belongs to.

string format: uuid

**person\_code**

Employee code of the person.

string

**person\_first\_name**

First name of the person.

string

**person\_last\_name**

Last name of the person.

string

**person\_is\_employee**

Whether the person is a company employee.

boolean

**person\_is\_external**

Whether the person is external prevention staff.

boolean

**person\_street**

Residential address.

string

**person\_locality**

City.

string

**person\_postal\_code**

Postal code.

string

**person\_region**

Region or province.

string

**person\_country**

Country code.

string

**person\_birth\_date**

Date of birth.

string

**person\_birth\_place**

Place of birth.

string

**person\_tax\_code**

Tax code (fiscal code).

string

**person\_note**

Free-text notes.

string

**person\_contract\_type**

Employment contract type.

string

**person\_entity\_id**

Email of the linked user account.

string

**person\_sex**

Sex.

string

**project\_name**

Name of the project (company).

string

**project\_type**

Type of the parent project.

string

Allowed values: safety template

**office\_code**

Code of the office.

string

**office\_name**

Name of the office.

string

**owned\_active**

Whether this assignment is currently active in its validity period.

boolean

nullable

**parent\_active**

Whether the parent entities (office, person) are 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. “-person\_last\_name”).

string

Allowed values: person\_code person\_first\_name person\_last\_name person\_birth\_date person\_tax\_code

**history**

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

boolean

##### Example

```
{  "filter": {    "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "person_last_name": "Smith"  },  "per-page": 50,  "page": 1,  "sort": "person_last_name"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of person-office assignments

Select media typeapplication/json

Array<object>

object

**person\_office\_id**

Unique identifier of the assignment.

string format: uuid

**office\_id**

The office the person is assigned to.

string format: uuid

**person\_id**

The assigned person.

string format: uuid

**project\_id**

The project this assignment belongs to.

string format: uuid

**person\_code**

Employee code of the person.

string

**person\_first\_name**

First name of the person.

string

**person\_last\_name**

Last name of the person.

string

**person\_is\_employee**

Whether the person is a company employee.

boolean

**person\_is\_external**

Whether the person is external prevention staff.

boolean

**person\_street**

Residential address.

string

**person\_locality**

City.

string

**person\_postal\_code**

Postal code.

string

**person\_region**

Region or province.

string

**person\_country**

Country code.

string

**person\_birth\_date**

Date of birth.

string

**person\_birth\_place**

Place of birth.

string

**person\_tax\_code**

Tax code (fiscal code).

string

**person\_note**

Free-text notes.

string

**person\_contract\_type**

Employment contract type.

string

**person\_entity\_id**

Email of the linked user account.

string

**person\_sex**

Sex.

string

**project\_name**

Name of the project (company).

string

**project\_type**

Type of the parent project.

string

Allowed values: safety template

**office\_code**

Code of the office.

string

**office\_name**

Name of the office.

string

**owned\_active**

Whether this assignment is currently active in its validity period.

boolean

nullable

**parent\_active**

Whether the parent entities (office, person) are currently active.

boolean

nullable

##### Example

```
[  {    "person_office_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",    "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",    "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",    "person_code": "JS001",    "person_first_name": "John",    "person_last_name": "Smith",    "person_tax_code": "SMTJHN85C15H501Z",    "person_birth_date": "1985-03-15",    "person_is_employee": true,    "office_name": "Rome North Site",    "office_code": "RN-001",    "project_name": "Acme Construction Ltd",    "project_type": "safety",    "owned_active": true,    "parent_active": true  }]
```

#### 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

### view

[Section titled “view”](#operation-viewPersonOffice-get)

GET

/v2/person-office/view/{id}

-   

Retrieves a single person-office assignment by its ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_office\_id to retrieve.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Person-office assignment found

Select media typeapplication/json

object

**person\_office\_id**

Unique identifier of the assignment.

string format: uuid

**office\_id**

The office the person is assigned to.

string format: uuid

**person\_id**

The assigned person.

string format: uuid

**project\_id**

The project this assignment belongs to.

string format: uuid

**person\_code**

Employee code of the person.

string

**person\_first\_name**

First name of the person.

string

**person\_last\_name**

Last name of the person.

string

**person\_is\_employee**

Whether the person is a company employee.

boolean

**person\_is\_external**

Whether the person is external prevention staff.

boolean

**person\_street**

Residential address.

string

**person\_locality**

City.

string

**person\_postal\_code**

Postal code.

string

**person\_region**

Region or province.

string

**person\_country**

Country code.

string

**person\_birth\_date**

Date of birth.

string

**person\_birth\_place**

Place of birth.

string

**person\_tax\_code**

Tax code (fiscal code).

string

**person\_note**

Free-text notes.

string

**person\_contract\_type**

Employment contract type.

string

**person\_entity\_id**

Email of the linked user account.

string

**person\_sex**

Sex.

string

**project\_name**

Name of the project (company).

string

**project\_type**

Type of the parent project.

string

Allowed values: safety template

**office\_code**

Code of the office.

string

**office\_name**

Name of the office.

string

**owned\_active**

Whether this assignment is currently active in its validity period.

boolean

nullable

**parent\_active**

Whether the parent entities (office, person) are currently active.

boolean

nullable

##### Example

```
{  "person_office_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",  "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "person_code": "JS001",  "person_first_name": "John",  "person_last_name": "Smith",  "person_tax_code": "SMTJHN85C15H501Z",  "person_birth_date": "1985-03-15",  "person_is_employee": true,  "office_name": "Rome North Site",  "office_code": "RN-001",  "project_name": "Acme Construction Ltd",  "project_type": "safety",  "owned_active": true,  "parent_active": true}
```

##### 404

[Section titled “404 ”](#404)

Person-office assignment not found

### create

[Section titled “create”](#operation-createPersonOffice-post)

POST

/v2/person-office/create

-   

Creates a new person-office assignment.

Requires `office_id`, `person_id`, and `project_id`. The `person_office_id` is auto-generated if not provided.

The person and the office must already exist and belong to the same project.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body required

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

Person-office assignment to create

Select media typeapplication/json

object

**person\_office\_id**

Unique identifier of the assignment. Auto-generated if not provided on creation.

string format: uuid

**office\_id**

required

The office (work location) the person is assigned to. Pass the `office_id` obtained from the Office API.

string format: uuid

**person\_id**

required

The person assigned to this office. Pass the `person_id` obtained from the Person API.

string format: uuid

**project\_id**

required

The project (company) this assignment belongs to. Must be the same project as both the person and the office.

string format: uuid

##### Example

```
{  "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 201

[Section titled “201 ”](#201)

Person-office assignment created successfully

Select media typeapplication/json

object

**person\_office\_id**

Unique identifier of the assignment. Auto-generated if not provided on creation.

string format: uuid

**office\_id**

required

The office (work location) the person is assigned to. Pass the `office_id` obtained from the Office API.

string format: uuid

**person\_id**

required

The person assigned to this office. Pass the `person_id` obtained from the Person API.

string format: uuid

**project\_id**

required

The project (company) this assignment belongs to. Must be the same project as both the person and the office.

string format: uuid

##### Example

```
{  "person_office_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",  "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"}
```

### update

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

PUT

/v2/person-office/update/{id}

-   

Updates an existing person-office assignment.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_office\_id to update.

#### Request Body required

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

Person-office fields to update

Select media typeapplication/json

object

**person\_office\_id**

Unique identifier of the assignment. Auto-generated if not provided on creation.

string format: uuid

**office\_id**

required

The office (work location) the person is assigned to. Pass the `office_id` obtained from the Office API.

string format: uuid

**person\_id**

required

The person assigned to this office. Pass the `person_id` obtained from the Person API.

string format: uuid

**project\_id**

required

The project (company) this assignment belongs to. Must be the same project as both the person and the office.

string format: uuid

##### Example

```
{  "office_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Person-office assignment updated successfully

Select media typeapplication/json

object

**person\_office\_id**

Unique identifier of the assignment. Auto-generated if not provided on creation.

string format: uuid

**office\_id**

required

The office (work location) the person is assigned to. Pass the `office_id` obtained from the Office API.

string format: uuid

**person\_id**

required

The person assigned to this office. Pass the `person_id` obtained from the Person API.

string format: uuid

**project\_id**

required

The project (company) this assignment belongs to. Must be the same project as both the person and the office.

string format: uuid

##### Example

```
{  "person_office_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",  "office_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"}
```

##### 404

[Section titled “404 ”](#404)

Person-office assignment not found

### delete

[Section titled “delete”](#operation-deletePersonOffice-delete)

DELETE

/v2/person-office/delete/{id}

-   

Deletes a person-office assignment.

If `force=false` (default), the operation is interrupted and the response lists child entities that would be deleted. If `force=true`, the assignment and all related entities are deleted.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_office\_id to delete.

#### Query Parameters

[Section titled “Query Parameters ”](#query-parameters)

**force**

boolean

If true, deletes the assignment and all child entities. If false, returns a preview of affected entities.

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Person-office assignment 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.