Skip to content
4HSE Developers DEV

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 ”

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/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 ”

Request Body

Section titled “Request Body ”

Parameters for searching person-office assignments

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 ”
200
Section titled “200 ”

List of person-office assignments

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 ”
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”
GET
/v2/person-office/view/{id}

Retrieves a single person-office assignment by its ID.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The person_office_id to retrieve.

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Person-office assignment found

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 ”

Person-office assignment not found

create

Section titled “create”
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 ”

Request Body required

Section titled “Request Body required ”

Person-office assignment to create

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 ”
201
Section titled “201 ”

Person-office assignment created successfully

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”
PUT
/v2/person-office/update/{id}

Updates an existing person-office assignment.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The person_office_id to update.

Request Body required

Section titled “Request Body required ”

Person-office fields to update

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 ”
200
Section titled “200 ”

Person-office assignment updated successfully

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 ”

Person-office assignment not found

delete

Section titled “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 ”

Path Parameters

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

The person_office_id to delete.

Query Parameters

Section titled “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 ”
204
Section titled “204 ”

Person-office assignment deleted successfully

400
Section titled “400 ”

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