---
title: "Person"
url: "https://dev.4hse.com/api/person"
---

# Person

A **Person** represents a worker or individual registered in a project (company). People belong to a project and are assigned to one or more offices via PersonOffice.

**Hierarchy:** Project (company) → Office (work location) → Person (worker).

People are the main subjects of the compliance schedule: action subscriptions (ActionSubscription) and certificates (Certificate) are typically linked to a person via their `person_id`.

Use this API to:

-   Find a person by name, last name, or tax code within a project
-   Get the `person_id` needed to create certificates, compliance schedule entries, or office assignments
-   Look up personal and employment details of a worker

A person can have a linked user account via `entity_id` (email) and `related_user` (permission level).

Version

2.0.0

OpenAPI version

3.0.0

## Authentication

[Section titled “ Authentication ”](#authentication)

### AccessToken

[Section titled “AccessToken ”](#accesstoken)

**Security scheme type:** apiKey

**Query parameter name:** access-token

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

## Operations

[Section titled “Operations”](#operations)

### index

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

POST

/v2/person/index

-   

Returns a paginated list of persons.

Most useful filters:

-   `project_id` + `last_name`: find a person by last name within a company
-   `project_id` + `tax_code`: find a person by tax code (exact match)
-   `project_id` + `code`: find a person by company employee code
-   `is_employee: 1`: filter employees only

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body

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

Parameters for searching persons

Select media typeapplication/json

object

**filter**

object

**person\_id**

Unique identifier of the person. Certificates reference the person via `resource_id`, compliance schedule entries via `subscriber_id` — pass this value.

string format: uuid

**code**

Alternative identifier, typically the company employee code.

string

<= 50 characters

**first\_name**

First name.

string

<= 70 characters

**last\_name**

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code).

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: company employee
-   `0`: not an employee

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: external prevention and safety staff
-   `0`: not external prevention staff

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account.

string

**project\_id**

The project (company) this person belongs to.

string format: uuid

**project\_name**

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

string

**project\_status**

Status of the parent project.

string

Allowed values: active suspended pending\_delete deleted

**project\_country**

Country of the parent project.

string

<= 50 characters

**related\_user**

Permission level of the linked user account:

-   `relatedUser_user`: basic access
-   `relatedUser_manager`: management access

string

**owned\_active**

Whether this person is currently active in their 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. “-last\_name”).

string

Allowed values: first\_name last\_name code tax\_code birth\_date

**history**

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

boolean

##### Example

```
{  "filter": {    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",    "last_name": "Smith",    "is_employee": 1  },  "per-page": 50,  "page": 1,  "sort": "last_name"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of persons

Select media typeapplication/json

Array<object>

object

**person\_id**

Unique identifier of the person. Certificates reference the person via `resource_id`, compliance schedule entries via `subscriber_id` — pass this value.

string format: uuid

**code**

Alternative identifier, typically the company employee code.

string

<= 50 characters

**first\_name**

First name.

string

<= 70 characters

**last\_name**

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code).

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: company employee
-   `0`: not an employee

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: external prevention and safety staff
-   `0`: not external prevention staff

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account.

string

**project\_id**

The project (company) this person belongs to.

string format: uuid

**project\_name**

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

string

**project\_status**

Status of the parent project.

string

Allowed values: active suspended pending\_delete deleted

**project\_country**

Country of the parent project.

string

<= 50 characters

**related\_user**

Permission level of the linked user account:

-   `relatedUser_user`: basic access
-   `relatedUser_manager`: management access

string

**owned\_active**

Whether this person is currently active in their validity period.

boolean

nullable

**parent\_active**

Whether the parent project is currently active.

boolean

nullable

##### Example

```
[  {    "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",    "first_name": "John",    "last_name": "Smith",    "code": "JS001",    "tax_code": "SMTJHN85C15H501Z",    "birth_date": "1985-03-15",    "is_employee": 1,    "is_prevention_people": 0,    "entity_id": "john.smith@example.com",    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",    "project_name": "Acme Construction Ltd",    "project_status": "active",    "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-viewPerson-get)

GET

/v2/person/view/{id}

-   

Retrieves a single person. Can be looked up in two ways:

-   By `person_id` (passed as path parameter `id`)
-   By `code` + `project_id` (passed as query parameters, if the `person_id` is not known)

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_id to retrieve. Required if `code` and `project_id` are not provided.

#### Query Parameters

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

**code**

string

Employee code. 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

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Person found

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Certificates reference the person via `resource_id`, compliance schedule entries via `subscriber_id` — pass this value.

string format: uuid

**code**

Alternative identifier, typically the company employee code.

string

<= 50 characters

**first\_name**

First name.

string

<= 70 characters

**last\_name**

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code).

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: company employee
-   `0`: not an employee

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: external prevention and safety staff
-   `0`: not external prevention staff

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account.

string

**project\_id**

The project (company) this person belongs to.

string format: uuid

**project\_name**

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

string

**project\_status**

Status of the parent project.

string

Allowed values: active suspended pending\_delete deleted

**project\_country**

Country of the parent project.

string

<= 50 characters

**related\_user**

Permission level of the linked user account:

-   `relatedUser_user`: basic access
-   `relatedUser_manager`: management access

string

**owned\_active**

Whether this person is currently active in their validity period.

boolean

nullable

**parent\_active**

Whether the parent project is currently active.

boolean

nullable

##### Example

```
{  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "first_name": "John",  "last_name": "Smith",  "code": "JS001",  "tax_code": "SMTJHN85C15H501Z",  "birth_date": "1985-03-15",  "is_employee": 1,  "is_prevention_people": 0,  "entity_id": "john.smith@example.com",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "project_name": "Acme Construction Ltd",  "project_status": "active",  "owned_active": true,  "parent_active": true}
```

##### 404

[Section titled “404 ”](#404)

Person not found

### create

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

POST

/v2/person/create

-   

Creates a new person within a project.

Requires `first_name`, `last_name`, and `project_id`. The `person_id` is auto-generated if not provided.

Creating a person does **not** assign them to any office. To assign a person to an office, create a PersonOffice after creating the person.

Special parameter `unique_code`: if `true` and a person with the same `code` already exists in the project, the existing person is updated instead of creating a new one. If the person was historicized, they are reactivated with a new period.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body required

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

Person object to be created

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Auto-generated if not provided on creation. Certificates reference the person via the `resource_id` field — pass this value. Compliance schedule entries reference the person via the `subscriber_id` field — pass this value. If unknown, use the index endpoint filtering by `project_id` and `last_name` or `tax_code` to find it.

string format: uuid

**code**

Alternative identifier, typically the company employee code. Can be used with `project_id` as an alternative to `person_id` for view, update, historicize, and delete operations.

string

<= 50 characters

**first\_name**

required

First name.

string

<= 70 characters

**last\_name**

required

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code). Useful for unique lookup within a project.

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: the person is a company employee
-   `0`: the person is not an employee Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: the person is external prevention and safety staff (e.g. external safety officer, occupational physician)
-   `0`: the person is not external prevention staff Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account. When set together with `related_user`, the person is connected to a platform account that can authenticate.

string

<= 50 characters

**project\_id**

required

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

string format: uuid

**related\_user**

The permission level of the linked user account on this person:

-   `relatedUser_user`: basic access to their own profile
-   `relatedUser_manager`: management access If not specified, inherited from the project configuration.

string

**unique\_code**

If true and a person with the same `code` already exists in the project, the existing person is updated instead of creating a new one. If the person was historicized, they are reactivated with a new period.

boolean

##### Example

```
{  "first_name": "John",  "last_name": "Smith",  "code": "JS001",  "tax_code": "SMTJHN85C15H501Z",  "birth_date": "1985-03-15",  "is_employee": 1,  "entity_id": "john.smith@example.com",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "related_user": "relatedUser_user"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 201

[Section titled “201 ”](#201)

Person created successfully

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Auto-generated if not provided on creation. Certificates reference the person via the `resource_id` field — pass this value. Compliance schedule entries reference the person via the `subscriber_id` field — pass this value. If unknown, use the index endpoint filtering by `project_id` and `last_name` or `tax_code` to find it.

string format: uuid

**code**

Alternative identifier, typically the company employee code. Can be used with `project_id` as an alternative to `person_id` for view, update, historicize, and delete operations.

string

<= 50 characters

**first\_name**

required

First name.

string

<= 70 characters

**last\_name**

required

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code). Useful for unique lookup within a project.

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: the person is a company employee
-   `0`: the person is not an employee Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: the person is external prevention and safety staff (e.g. external safety officer, occupational physician)
-   `0`: the person is not external prevention staff Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account. When set together with `related_user`, the person is connected to a platform account that can authenticate.

string

<= 50 characters

**project\_id**

required

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

string format: uuid

**related\_user**

The permission level of the linked user account on this person:

-   `relatedUser_user`: basic access to their own profile
-   `relatedUser_manager`: management access If not specified, inherited from the project configuration.

string

##### Example

```
{  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "first_name": "John",  "last_name": "Smith",  "code": "JS001",  "tax_code": "SMTJHN85C15H501Z",  "birth_date": "1985-03-15",  "is_employee": 1,  "entity_id": "john.smith@example.com",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "related_user": "relatedUser_user"}
```

### update

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

PUT

/v2/person/update/{id}

-   

Updates an existing person. Can be identified by `person_id` or by `code` + `project_id`.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_id to update. Required if `code` and `project_id` are not provided.

#### Query Parameters

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

**code**

string

Employee code. 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

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

Person fields to update

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Auto-generated if not provided on creation. Certificates reference the person via the `resource_id` field — pass this value. Compliance schedule entries reference the person via the `subscriber_id` field — pass this value. If unknown, use the index endpoint filtering by `project_id` and `last_name` or `tax_code` to find it.

string format: uuid

**code**

Alternative identifier, typically the company employee code. Can be used with `project_id` as an alternative to `person_id` for view, update, historicize, and delete operations.

string

<= 50 characters

**first\_name**

required

First name.

string

<= 70 characters

**last\_name**

required

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code). Useful for unique lookup within a project.

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: the person is a company employee
-   `0`: the person is not an employee Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: the person is external prevention and safety staff (e.g. external safety officer, occupational physician)
-   `0`: the person is not external prevention staff Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account. When set together with `related_user`, the person is connected to a platform account that can authenticate.

string

<= 50 characters

**project\_id**

required

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

string format: uuid

**related\_user**

The permission level of the linked user account on this person:

-   `relatedUser_user`: basic access to their own profile
-   `relatedUser_manager`: management access If not specified, inherited from the project configuration.

string

##### Example

```
{  "last_name": "Johnson",  "code": "JJ002"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Person updated successfully

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Auto-generated if not provided on creation. Certificates reference the person via the `resource_id` field — pass this value. Compliance schedule entries reference the person via the `subscriber_id` field — pass this value. If unknown, use the index endpoint filtering by `project_id` and `last_name` or `tax_code` to find it.

string format: uuid

**code**

Alternative identifier, typically the company employee code. Can be used with `project_id` as an alternative to `person_id` for view, update, historicize, and delete operations.

string

<= 50 characters

**first\_name**

required

First name.

string

<= 70 characters

**last\_name**

required

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code). Useful for unique lookup within a project.

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: the person is a company employee
-   `0`: the person is not an employee Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: the person is external prevention and safety staff (e.g. external safety officer, occupational physician)
-   `0`: the person is not external prevention staff Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account. When set together with `related_user`, the person is connected to a platform account that can authenticate.

string

<= 50 characters

**project\_id**

required

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

string format: uuid

**related\_user**

The permission level of the linked user account on this person:

-   `relatedUser_user`: basic access to their own profile
-   `relatedUser_manager`: management access If not specified, inherited from the project configuration.

string

##### Example

```
{  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "first_name": "John",  "last_name": "Johnson",  "code": "JJ002"}
```

##### 404

[Section titled “404 ”](#404)

Person not found

### historicize

[Section titled “historicize”](#operation-historicizePerson-post)

POST

/v2/person/historicize/{id}

-   

Historicizes a person — marks them as no longer active from a specified date. The person and their data remain in the system but will not appear in normal queries. Use the `history: true` parameter in the index to include historicized persons.

If no date is specified, the current date is used.

Historicization propagates automatically: all child entities of the person (office assignments, compliance schedule entries, etc.) are excluded from normal queries without any direct changes to their data. The `parent_active` field in child entity responses reflects this state. This applies at all levels of the hierarchy.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_id to historicize. Required if `code` and `project_id` are not provided.

#### Query Parameters

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

**code**

string

Employee code. 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

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

Historicization date

Select media typeapplication/json

object

**date**

The date from which the person is no longer active. Defaults to the current date.

string format: date

##### Example

```
{  "date": "2025-06-10"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Person historicized successfully

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Auto-generated if not provided on creation. Certificates reference the person via the `resource_id` field — pass this value. Compliance schedule entries reference the person via the `subscriber_id` field — pass this value. If unknown, use the index endpoint filtering by `project_id` and `last_name` or `tax_code` to find it.

string format: uuid

**code**

Alternative identifier, typically the company employee code. Can be used with `project_id` as an alternative to `person_id` for view, update, historicize, and delete operations.

string

<= 50 characters

**first\_name**

required

First name.

string

<= 70 characters

**last\_name**

required

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code). Useful for unique lookup within a project.

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: the person is a company employee
-   `0`: the person is not an employee Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: the person is external prevention and safety staff (e.g. external safety officer, occupational physician)
-   `0`: the person is not external prevention staff Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account. When set together with `related_user`, the person is connected to a platform account that can authenticate.

string

<= 50 characters

**project\_id**

required

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

string format: uuid

**related\_user**

The permission level of the linked user account on this person:

-   `relatedUser_user`: basic access to their own profile
-   `relatedUser_manager`: management access If not specified, inherited from the project configuration.

string

##### 404

[Section titled “404 ”](#404)

Person not found

### delete

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

DELETE

/v2/person/delete/{id}

-   

Deletes a person. Can be identified by `person_id` or by `code` + `project_id`.

With `historicize=true`, the person is historicized instead of deleted (equivalent to the historicize endpoint). If `force=false` (default), the operation is interrupted and the response lists related entities. If `force=true`, the person and all related entities are deleted.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_id to delete. Required if `code` and `project_id` are not provided.

#### Query Parameters

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

**code**

string

Employee code. 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 is historicized instead of deleted.

**force**

boolean

If true, deletes the person and all related entities. If false, returns a preview of affected entities.

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Person deleted successfully

##### 400

[Section titled “400 ”](#400)

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

### verify

[Section titled “verify”](#operation-verifyPerson-get)

GET

/v2/person/verify/{id}

-   

Returns aggregated person data for public badge verification. Includes personal details, employer info, profile photo, and certificates with status.

Accessible by authenticated users and via UrlSign (pre-signed URL). Attachment and photo URLs in the response are pre-signed with a 24h TTL.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The person\_id to verify.

#### Query Parameters

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

**urlsign**

string

URL signature token for unauthenticated access.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Person verification data

Select media typeapplication/json

object

**person**

object

**first\_name**

string

**last\_name**

string

**tax\_code**

string

nullable

**birth\_date**

string format: date

nullable

**profile\_photo\_url**

Pre-signed URL to the profile photo (24h TTL)

string

nullable

**employer**

object

**name**

string

**project\_id**

string format: uuid

**certificates**

Array<object>

object

**certificate\_id**

string format: uuid

**name**

string

**action\_type**

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

**date\_release**

string format: date

**date\_expire**

string format: date

nullable

**status**

string

Allowed values: valid expired expiring

**attachment\_urls**

Pre-signed URLs to certificate attachments (24h TTL)

Array<string>

##### 404

[Section titled “404 ”](#404)

Person not found

## Webhooks

[Section titled “Webhooks”](#webhooks)

#### PERSON::CREATE

[Section titled “PERSON::CREATE”](#webhook-PERSON::CREATE)

POST

Triggered when a new person is created.

#### Request Body

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

The newly created person

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Auto-generated if not provided on creation. Certificates reference the person via the `resource_id` field — pass this value. Compliance schedule entries reference the person via the `subscriber_id` field — pass this value. If unknown, use the index endpoint filtering by `project_id` and `last_name` or `tax_code` to find it.

string format: uuid

**code**

Alternative identifier, typically the company employee code. Can be used with `project_id` as an alternative to `person_id` for view, update, historicize, and delete operations.

string

<= 50 characters

**first\_name**

required

First name.

string

<= 70 characters

**last\_name**

required

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code). Useful for unique lookup within a project.

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: the person is a company employee
-   `0`: the person is not an employee Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: the person is external prevention and safety staff (e.g. external safety officer, occupational physician)
-   `0`: the person is not external prevention staff Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account. When set together with `related_user`, the person is connected to a platform account that can authenticate.

string

<= 50 characters

**project\_id**

required

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

string format: uuid

**related\_user**

The permission level of the linked user account on this person:

-   `relatedUser_user`: basic access to their own profile
-   `relatedUser_manager`: management access If not specified, inherited from the project configuration.

string

##### Example

```
{  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "first_name": "John",  "last_name": "Smith",  "code": "JS001",  "birth_date": "1985-03-15",  "entity_id": "john.smith@example.com",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "related_user": "relatedUser_user"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Acknowledgment of the webhook event

#### PERSON::UPDATE

[Section titled “PERSON::UPDATE”](#webhook-PERSON::UPDATE)

POST

Triggered when a person is updated. Provides the person ID and an object containing old and new values for each updated field.

#### Request Body

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

Updated person with old and new values for changed fields

Select media typeapplication/json

object

**entity\_id**

required

The person\_id of the updated person.

string format: uuid

**updated\_fields**

required

Each key is an updated field name, with its old and new values.

object

**_key_**

additional properties

object

**old**

**new**

##### Example

```
{  "entity_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "updated_fields": {    "last_name": {      "new": "Johnson",      "old": "Smith"    }  }}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Acknowledgment of the webhook event

#### PERSON::DELETE

[Section titled “PERSON::DELETE”](#webhook-PERSON::DELETE)

POST

Triggered when a person is deleted.

#### Request Body

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

The deleted person

Select media typeapplication/json

object

**person\_id**

Unique identifier of the person. Auto-generated if not provided on creation. Certificates reference the person via the `resource_id` field — pass this value. Compliance schedule entries reference the person via the `subscriber_id` field — pass this value. If unknown, use the index endpoint filtering by `project_id` and `last_name` or `tax_code` to find it.

string format: uuid

**code**

Alternative identifier, typically the company employee code. Can be used with `project_id` as an alternative to `person_id` for view, update, historicize, and delete operations.

string

<= 50 characters

**first\_name**

required

First name.

string

<= 70 characters

**last\_name**

required

Last name.

string

<= 70 characters

**street**

Residential address.

string

<= 255 characters

**locality**

City.

string

<= 50 characters

**postal\_code**

Postal code.

string

<= 50 characters

**region**

Region or province.

string

<= 150 characters

**sex**

Sex.

string

<= 10 characters

**country**

ISO 3166-1 alpha-2 country code.

string

<= 50 characters

**birth\_date**

Date of birth.

string format: date

**birth\_place**

Place of birth.

string

<= 150 characters

**tax\_code**

Tax code (fiscal code). Useful for unique lookup within a project.

string

<= 30 characters

**note**

Free-text notes.

string

**contract\_type**

Employment contract type.

string

**is\_employee**

-   `1`: the person is a company employee
-   `0`: the person is not an employee Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**is\_prevention\_people**

-   `1`: the person is external prevention and safety staff (e.g. external safety officer, occupational physician)
-   `0`: the person is not external prevention staff Normally a person is either an employee (`is_employee: 1`) or external prevention staff (`is_prevention_people: 1`), not both.

integer

Allowed values: 0 1

**entity\_id**

The email of the linked user account. When set together with `related_user`, the person is connected to a platform account that can authenticate.

string

<= 50 characters

**project\_id**

required

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

string format: uuid

**related\_user**

The permission level of the linked user account on this person:

-   `relatedUser_user`: basic access to their own profile
-   `relatedUser_manager`: management access If not specified, inherited from the project configuration.

string

##### Example

```
{  "person_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",  "first_name": "John",  "last_name": "Smith",  "code": "JS001",  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Acknowledgment of the webhook event

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.