Person

Represents a person with their relevant details. A person can be associated with offices, projects, and roles within the system. Optionally, a linked user account (related_user) can be assigned, enabling authentication with that identity.

Version

2.0.0

OpenAPI version

3.1.0

Authentication

AccessToken

Security scheme type: apiKey

Query parameter name: access-token

OAuth2

Security scheme type: oauth2

Flow type: password

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

Operations

index

POST

/v2/person/index

Returns a paginated and filterable list of persons. Use POST to allow complex filters via JSON payload.

Authorizations

• AccessToken
• OAuth2

Request Body

Parameters for searching persons

object

filter

object

person_id

string format: uuid

code

string

<= 50 characters

first_name

string

<= 70 characters

last_name

string

<= 70 characters

street

string

<= 255 characters

locality

string

<= 50 characters

postal_code

string

<= 50 characters

region

string

<= 10 characters

sex

string

<= 10 characters

country

string

<= 50 characters

birth_date

string format: date

birth_place

string

<= 150 characters

tax_code

string

<= 30 characters

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

string

project_id

string format: uuid

project_name

string

per-page

integer

default: 100 >= 1

page

integer

default: 1 >= 1

sort

string

Allowed values: first_name last_name code tax_code birth_date

history

boolean

Example

{
  "filter": {
    "first_name": "Mario",
    "last_name": "Rossi",
    "related_user": "relatedUser_manager",
    "entity_id": "mario.rossi@4hse.com"
  },
  "per-page": 50,
  "page": 2,
  "sort": "-last_name"
}

Responses

200

List of persons

Array<object>

object

person_id

string format: uuid

code

string

<= 50 characters

first_name

string

<= 70 characters

last_name

string

<= 70 characters

street

string

<= 255 characters

locality

string

<= 50 characters

postal_code

string

<= 50 characters

region

string

<= 10 characters

sex

string

<= 10 characters

country

string

<= 50 characters

birth_date

string format: date

birth_place

string

<= 150 characters

tax_code

string

<= 30 characters

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

string

project_id

string format: uuid

project_name

string

related_user

string

owned_active

boolean

parent_active

boolean

Example

{
  "person_id": "person-1",
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR001",
  "birth_date": "1980-01-01",
  "entity_id": "mario.rossi@4hse.com",
  "project_id": "proj-1",
  "related_user": "relatedUser_manager"
}

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

GET

/v2/person/view/{id}

Retrieve a person by its unique ID.

Authorizations

• AccessToken
• OAuth2

Path Parameters

id

required

string format: uuid

ID of the person to retrieve. Required if code and project_id are not provided.

Query Parameters

code

string

Code of the person to get. Required together with project_id if id is not provided

project_id

string format: uuid

Required together with code if id is not provided

Responses

200

Person found

object

person_id

string format: uuid

code

string

<= 50 characters

first_name

string

<= 70 characters

last_name

string

<= 70 characters

street

string

<= 255 characters

locality

string

<= 50 characters

postal_code

string

<= 50 characters

region

string

<= 10 characters

sex

string

<= 10 characters

country

string

<= 50 characters

birth_date

string format: date

birth_place

string

<= 150 characters

tax_code

string

<= 30 characters

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

string

project_id

string format: uuid

project_name

string

related_user

string

owned_active

boolean

parent_active

boolean

Example

{
  "person_id": "person-1",
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR001",
  "birth_date": "1980-01-01",
  "entity_id": "mario.rossi@4hse.com",
  "project_id": "proj-1",
  "related_user": "relatedUser_manager"
}

404

Person not found

create

POST

/v2/person/create

Create a new person by providing the required details.

Authorizations

• AccessToken
• OAuth2

Request Body ^required

Person object to be created

object

person_id

required

string

code

string

first_name

required

string

last_name

required

string

street

string

locality

string

postal_code

string

region

string

sex

string

country

string

birth_date

required

string format: date

birth_place

string

tax_code

string

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

required

string

project_id

required

string

related_user

required

string

unique_code

If true and a person with the same code already exists, the person will be updated instead of created. If the person was historicized, a new period will be started.

boolean

Example

{
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR001",
  "birth_date": "1980-01-01",
  "entity_id": "mario.rossi@4hse.com",
  "project_id": "proj-1",
  "related_user": "relatedUser_manager"
}

Responses

201

Person created successfully

object

person_id

required

string

code

string

first_name

required

string

last_name

required

string

street

string

locality

string

postal_code

string

region

string

sex

string

country

string

birth_date

required

string format: date

birth_place

string

tax_code

string

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

required

string

project_id

required

string

related_user

required

string

Example

{
  "person_id": "person-2",
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR001",
  "birth_date": "1980-01-01",
  "entity_id": "mario.rossi@4hse.com",
  "project_id": "proj-1",
  "related_user": "relatedUser_manager"
}

update

PUT

/v2/person/update/{id}

Update an existing person by its unique ID.

Authorizations

• AccessToken
• OAuth2

Path Parameters

id

required

string format: uuid

ID of the person to update. Required if code and project_id are not provided.

Query Parameters

code

string

Code of the person to update. Required together with project_id if id is not provided

project_id

string format: uuid

Required together with code if id is not provided

Request Body ^required

Person object with updated data

object

person_id

required

string

code

string

first_name

required

string

last_name

required

string

street

string

locality

string

postal_code

string

region

string

sex

string

country

string

birth_date

required

string format: date

birth_place

string

tax_code

string

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

required

string

project_id

required

string

related_user

required

string

Example

{
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR002"
}

Responses

200

Person updated successfully

object

person_id

required

string

code

string

first_name

required

string

last_name

required

string

street

string

locality

string

postal_code

string

region

string

sex

string

country

string

birth_date

required

string format: date

birth_place

string

tax_code

string

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

required

string

project_id

required

string

related_user

required

string

Example

{
  "person_id": "person-1",
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR002"
}

404

Person not found

historicize

POST

/v2/person/historicize/{id}

Historicize an existing person.

Authorizations

• AccessToken
• OAuth2

Path Parameters

id

required

string format: uuid

ID of the person to historicize. Required if code and project_id are not provided.

Query Parameters

code

string

Code of the person to historicize. Required together with project_id if id is not provided

project_id

string format: uuid

Required together with code if id is not provided

Request Body

Date used to historicize the person

object

date

The date of the historicization. If not provided, the current date will be used.

string format: date

Responses

200

Person historicized successfully

object

person_id

required

string

code

string

first_name

required

string

last_name

required

string

street

string

locality

string

postal_code

string

region

string

sex

string

country

string

birth_date

required

string format: date

birth_place

string

tax_code

string

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

required

string

project_id

required

string

related_user

required

string

404

Person not found

delete

DELETE

/v2/person/delete/{id}

Delete a person by its unique ID. If force=true, all related entities will also be deleted.

Authorizations

• AccessToken
• OAuth2

Path Parameters

id

required

string format: uuid

ID of the person to delete. Required if code and project_id are not provided.

Query Parameters

code

string

Code of the person to delete. Required together with project_id if id is not provided

project_id

string format: uuid

Required together with code if id is not provided

historicize

boolean

If true, the person will be historicized instead of deleted.

force

boolean

Force the deletion of the entity and all related entities

Responses

204

Person deleted successfully

400

If force=false, the operation is interrupted and the list of connected entities that will be deleted in case of confirmation (force=true) is returned

Webhooks

PERSON::CREATE

POST

This webhook is triggered when a new person is created in the system. It provides the details of the newly created person.

Request Body

Information about the newly created person

object

person_id

required

string

code

string

first_name

required

string

last_name

required

string

street

string

locality

string

postal_code

string

region

string

sex

string

country

string

birth_date

required

string format: date

birth_place

string

tax_code

string

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

required

string

project_id

required

string

related_user

required

string

Example

{
  "person_id": "person-2",
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR001",
  "birth_date": "1980-01-01",
  "entity_id": "mario.rossi@4hse.com",
  "project_id": "proj-1",
  "related_user": "relatedUser_manager"
}

Responses

200

Acknowledgment of the webhook event

PERSON::UPDATE

POST

This webhook is triggered when a person is updated in the system. It provides the unique ID of the person and an object containing the old and new values for each updated field.

Request Body

Information about the updated person, with old and new values for the changed properties.

object

entity_id

required

The unique ID of the updated person.

string format: uuid

updated_fields

required

An object where each key is the name of an updated field, and its value contains the old and new values.

object

key

additional properties

Provides the old and new value for a property. The type of the values depends on the specific property.

object

old

new

Example

{
  "entity_id": "d9a77e06-9b47-4829-b28a-c7561deac771",
  "updated_fields": {
    "last_name": {
      "new": "Rossini",
      "old": "Rossi"
    },
    "birth_date": {
      "new": "",
      "old": null
    }
  }
}

Responses

200

Acknowledgment of the webhook event

PERSON::DELETE

POST

This webhook is triggered when a person is deleted from the system. It provides the deleted person.

Request Body

Information about the deleted person

object

person_id

required

string

code

string

first_name

required

string

last_name

required

string

street

string

locality

string

postal_code

string

region

string

sex

string

country

string

birth_date

required

string format: date

birth_place

string

tax_code

string

note

string

contract_type

string

is_employee

integer

Allowed values: 0 1

is_prevention_people

integer

Allowed values: 0 1

entity_id

required

string

project_id

required

string

related_user

required

string

Example

{
  "person_id": "person-2",
  "first_name": "Mario",
  "last_name": "Rossi",
  "code": "MR001",
  "birth_date": "1980-01-01",
  "entity_id": "mario.rossi@4hse.com",
  "project_id": "proj-1",
  "related_user": "relatedUser_manager"
}

Responses

200

Acknowledgment of the webhook event