---
title: "Project"
url: "https://dev.4hse.com/api/project"
---

# Project

A **Project** represents a company in 4HSE. Every operation on the platform happens within the scope of a project: offices, people, actions, certificates, and compliance data all belong to a project.

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

Other APIs reference the project via the `tenant_id` field — pass the `project_id`.

Use this API to:

-   Find the company you want to operate on (e.g. search for “Acme Construction Ltd”)
-   List all projects accessible by the authenticated user
-   Check project status — only projects with `status: active` are operational

A customer with multiple companies has multiple projects. Each multi-company customer also has a project with `project_type: template`, which contains reference data, forms, and print templates reusable by operational projects and work locations.

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

POST

/v2/project/index

-   

Returns a paginated list of projects accessible by the authenticated user.

Most useful filters:

-   `name`: search a project by company name
-   `status: active`: exclude suspended or deleted projects
-   `project_type: safety`: exclude template projects

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body

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

Parameters for searching projects

Select media typeapplication/json

object

**filter**

object

**project\_id**

Unique identifier of the project. Other APIs reference the project via the `tenant_id` field — pass this value.

string format: uuid

**name**

The company name.

string

<= 50 characters

**description**

Optional free-text description.

string

nullable

**country**

ISO 3166-1 alpha-2 country code.

string

**status**

Project lifecycle status:

-   `active`: fully operational
-   `suspended`: temporarily disabled
-   `pending_delete`: scheduled for deletion
-   `deleted`: permanently deleted

string

Allowed values: active suspended pending\_delete deleted

**project\_type**

-   `safety`: operational company project
-   `template`: container for reference data, forms, and print templates

string

Allowed values: safety template

**data**

Additional structured data in JSON format.

object

**icon**

URL of the project icon image.

string format: url

<= 255 characters

**npeople**

Number of active workers in this project.

integer

**subscription\_id**

The subscription governing access to this project.

string format: uuid

**customer\_id**

The customer (billing entity) that owns this project.

string format: uuid

**partner\_id**

The partner managing this project.

string format: uuid

**created\_at**

Date when the project was created.

string format: date

**updated\_at**

Date when the project was last modified.

string format: date

**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 status project\_type country created\_at

**history**

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

boolean

##### Example

```
{  "filter": {    "name": "Acme Construction",    "project_type": "safety"  },  "per-page": 20,  "page": 1,  "sort": "name"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of projects

Select media typeapplication/json

Array<object>

object

**project\_id**

Unique identifier of the project. Other APIs reference the project via the `tenant_id` field — pass this value.

string format: uuid

**name**

The company name.

string

<= 50 characters

**description**

Optional free-text description.

string

nullable

**country**

ISO 3166-1 alpha-2 country code.

string

**status**

Project lifecycle status:

-   `active`: fully operational
-   `suspended`: temporarily disabled
-   `pending_delete`: scheduled for deletion
-   `deleted`: permanently deleted

string

Allowed values: active suspended pending\_delete deleted

**project\_type**

-   `safety`: operational company project
-   `template`: container for reference data, forms, and print templates

string

Allowed values: safety template

**data**

Additional structured data in JSON format.

object

**icon**

URL of the project icon image.

string format: url

<= 255 characters

**npeople**

Number of active workers in this project.

integer

**subscription\_id**

The subscription governing access to this project.

string format: uuid

**customer\_id**

The customer (billing entity) that owns this project.

string format: uuid

**partner\_id**

The partner managing this project.

string format: uuid

**created\_at**

Date when the project was created.

string format: date

**updated\_at**

Date when the project was last modified.

string format: date

##### Example

```
[  {    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",    "name": "Acme Construction Ltd",    "description": "Safety management for Acme Construction sites",    "country": "IT",    "status": "active",    "project_type": "safety",    "npeople": 47,    "customer_id": "c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",    "partner_id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",    "created_at": "2023-06-15",    "updated_at": "2024-11-20"  }]
```

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

POST

/v2/project/create

-   

Creates a new project (company).

Requires `name` and `country`. The `project_id` is auto-generated if not provided. By default the project is created with `status: active` and `project_type: safety`.

After creation, the folder structure for file storage is prepared automatically. The typical next step is to create offices/work locations via the Office API.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body required

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

Project object to be created

Select media typeapplication/json

object

**project\_id**

Unique identifier of the project. Auto-generated if not provided on creation. Other APIs reference the project via the `tenant_id` field — pass this value. If unknown, use the index endpoint filtering by `name` to find it.

string format: uuid

**name**

required

The company name.

string

<= 50 characters

**description**

Optional free-text description.

string

nullable

**country**

required

ISO 3166-1 alpha-2 country code (e.g. “IT”, “DE”).

string

<= 2 characters

**status**

Project lifecycle status:

-   `active`: fully operational, all operations are allowed
-   `suspended`: temporarily disabled, data is preserved but operations may be restricted
-   `pending_delete`: scheduled for deletion, will be permanently removed at the date in `deleted_at`
-   `deleted`: permanently deleted

string

Allowed values: active suspended pending\_delete deleted

**project\_type**

-   `safety`: an operational company project — the standard type
-   `template`: a container for reference data, forms, and print templates. Not an operational company. Each multi-company customer has one, and its contents are reusable by operational projects and work locations.

string

Allowed values: safety template

**data**

Additional structured data in JSON format.

object

**icon**

URL of the project icon image.

string format: url

<= 255 characters

**npeople**

Number of active workers in this project.

integer

**subscription\_id**

The subscription governing access to this project. A project is only operational if its subscription is active.

string format: uuid

**customer\_id**

The customer (billing entity) that owns this project.

string format: uuid

**partner\_id**

The partner managing this project.

string format: uuid

**created\_at**

Date when the project was created.

string format: date

**updated\_at**

Date when the project was last modified.

string format: date

**deleted\_at**

Scheduled deletion date. Cleared when status is set back to `active` or `suspended`.

string format: date

##### Example

```
{  "name": "Acme Construction Ltd",  "description": "Safety management for Acme Construction sites",  "country": "IT",  "project_type": "safety",  "customer_id": "c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",  "partner_id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 201

[Section titled “201 ”](#201)

Project created successfully

Select media typeapplication/json

object

**project\_id**

Unique identifier of the project. Auto-generated if not provided on creation. Other APIs reference the project via the `tenant_id` field — pass this value. If unknown, use the index endpoint filtering by `name` to find it.

string format: uuid

**name**

required

The company name.

string

<= 50 characters

**description**

Optional free-text description.

string

nullable

**country**

required

ISO 3166-1 alpha-2 country code (e.g. “IT”, “DE”).

string

<= 2 characters

**status**

Project lifecycle status:

-   `active`: fully operational, all operations are allowed
-   `suspended`: temporarily disabled, data is preserved but operations may be restricted
-   `pending_delete`: scheduled for deletion, will be permanently removed at the date in `deleted_at`
-   `deleted`: permanently deleted

string

Allowed values: active suspended pending\_delete deleted

**project\_type**

-   `safety`: an operational company project — the standard type
-   `template`: a container for reference data, forms, and print templates. Not an operational company. Each multi-company customer has one, and its contents are reusable by operational projects and work locations.

string

Allowed values: safety template

**data**

Additional structured data in JSON format.

object

**icon**

URL of the project icon image.

string format: url

<= 255 characters

**npeople**

Number of active workers in this project.

integer

**subscription\_id**

The subscription governing access to this project. A project is only operational if its subscription is active.

string format: uuid

**customer\_id**

The customer (billing entity) that owns this project.

string format: uuid

**partner\_id**

The partner managing this project.

string format: uuid

**created\_at**

Date when the project was created.

string format: date

**updated\_at**

Date when the project was last modified.

string format: date

**deleted\_at**

Scheduled deletion date. Cleared when status is set back to `active` or `suspended`.

string format: date

##### Example

```
{  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "name": "Acme Construction Ltd",  "description": "Safety management for Acme Construction sites",  "country": "IT",  "status": "active",  "project_type": "safety",  "customer_id": "c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",  "partner_id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",  "created_at": "2024-01-15",  "updated_at": "2024-01-15"}
```

### view

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

GET

/v2/project/view/{id}

-   

Retrieves a single project by its ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The project\_id to retrieve.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Project found

Select media typeapplication/json

object

**project\_id**

Unique identifier of the project. Other APIs reference the project via the `tenant_id` field — pass this value.

string format: uuid

**name**

The company name.

string

<= 50 characters

**description**

Optional free-text description.

string

nullable

**country**

ISO 3166-1 alpha-2 country code.

string

**status**

Project lifecycle status:

-   `active`: fully operational
-   `suspended`: temporarily disabled
-   `pending_delete`: scheduled for deletion
-   `deleted`: permanently deleted

string

Allowed values: active suspended pending\_delete deleted

**project\_type**

-   `safety`: operational company project
-   `template`: container for reference data, forms, and print templates

string

Allowed values: safety template

**data**

Additional structured data in JSON format.

object

**icon**

URL of the project icon image.

string format: url

<= 255 characters

**npeople**

Number of active workers in this project.

integer

**subscription\_id**

The subscription governing access to this project.

string format: uuid

**customer\_id**

The customer (billing entity) that owns this project.

string format: uuid

**partner\_id**

The partner managing this project.

string format: uuid

**created\_at**

Date when the project was created.

string format: date

**updated\_at**

Date when the project was last modified.

string format: date

##### Example

```
{  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "name": "Acme Construction Ltd",  "description": "Safety management for Acme Construction sites",  "country": "IT",  "status": "active",  "project_type": "safety",  "npeople": 47,  "customer_id": "c8d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",  "partner_id": "d1e2f3a4-5b6c-7d8e-9f0a-1b2c3d4e5f6a",  "created_at": "2023-06-15",  "updated_at": "2024-11-20"}
```

##### 404

[Section titled “404 ”](#404)

Project not found

### delete

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

DELETE

/v2/project/delete/{id}

-   

Deletes a project. The project is scheduled for deletion (`status: pending_delete`) and will be permanently removed at the date indicated in `deleted_at`.

If `force=false` (default), the operation is interrupted and the response lists all child entities (offices, people, actions, certificates) that would be deleted. Use this to evaluate the impact. If `force=true`, the scheduled deletion is confirmed.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The project\_id to delete.

#### Query Parameters

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

**force**

boolean

If true, confirms the scheduled deletion of the project 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)

Project scheduled for deletion

##### 400

[Section titled “400 ”](#400)

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

### update

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

PUT

/v2/project/update/{id}

-   

Updates an existing project.

Common use cases: changing the project name, suspending a project (`status: suspended`), updating the description. Setting `status` to `active` or `suspended` clears the deletion date.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The project\_id to update.

#### Request Body required

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

Project fields to update

Select media typeapplication/json

object

**project\_id**

Unique identifier of the project. Auto-generated if not provided on creation. Other APIs reference the project via the `tenant_id` field — pass this value. If unknown, use the index endpoint filtering by `name` to find it.

string format: uuid

**name**

required

The company name.

string

<= 50 characters

**description**

Optional free-text description.

string

nullable

**country**

required

ISO 3166-1 alpha-2 country code (e.g. “IT”, “DE”).

string

<= 2 characters

**status**

Project lifecycle status:

-   `active`: fully operational, all operations are allowed
-   `suspended`: temporarily disabled, data is preserved but operations may be restricted
-   `pending_delete`: scheduled for deletion, will be permanently removed at the date in `deleted_at`
-   `deleted`: permanently deleted

string

Allowed values: active suspended pending\_delete deleted

**project\_type**

-   `safety`: an operational company project — the standard type
-   `template`: a container for reference data, forms, and print templates. Not an operational company. Each multi-company customer has one, and its contents are reusable by operational projects and work locations.

string

Allowed values: safety template

**data**

Additional structured data in JSON format.

object

**icon**

URL of the project icon image.

string format: url

<= 255 characters

**npeople**

Number of active workers in this project.

integer

**subscription\_id**

The subscription governing access to this project. A project is only operational if its subscription is active.

string format: uuid

**customer\_id**

The customer (billing entity) that owns this project.

string format: uuid

**partner\_id**

The partner managing this project.

string format: uuid

**created\_at**

Date when the project was created.

string format: date

**updated\_at**

Date when the project was last modified.

string format: date

**deleted\_at**

Scheduled deletion date. Cleared when status is set back to `active` or `suspended`.

string format: date

##### Example

```
{  "name": "Acme Construction Ltd - Rome",  "status": "suspended"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Project updated successfully

Select media typeapplication/json

object

**project\_id**

Unique identifier of the project. Auto-generated if not provided on creation. Other APIs reference the project via the `tenant_id` field — pass this value. If unknown, use the index endpoint filtering by `name` to find it.

string format: uuid

**name**

required

The company name.

string

<= 50 characters

**description**

Optional free-text description.

string

nullable

**country**

required

ISO 3166-1 alpha-2 country code (e.g. “IT”, “DE”).

string

<= 2 characters

**status**

Project lifecycle status:

-   `active`: fully operational, all operations are allowed
-   `suspended`: temporarily disabled, data is preserved but operations may be restricted
-   `pending_delete`: scheduled for deletion, will be permanently removed at the date in `deleted_at`
-   `deleted`: permanently deleted

string

Allowed values: active suspended pending\_delete deleted

**project\_type**

-   `safety`: an operational company project — the standard type
-   `template`: a container for reference data, forms, and print templates. Not an operational company. Each multi-company customer has one, and its contents are reusable by operational projects and work locations.

string

Allowed values: safety template

**data**

Additional structured data in JSON format.

object

**icon**

URL of the project icon image.

string format: url

<= 255 characters

**npeople**

Number of active workers in this project.

integer

**subscription\_id**

The subscription governing access to this project. A project is only operational if its subscription is active.

string format: uuid

**customer\_id**

The customer (billing entity) that owns this project.

string format: uuid

**partner\_id**

The partner managing this project.

string format: uuid

**created\_at**

Date when the project was created.

string format: date

**updated\_at**

Date when the project was last modified.

string format: date

**deleted\_at**

Scheduled deletion date. Cleared when status is set back to `active` or `suspended`.

string format: date

##### Example

```
{  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",  "name": "Acme Construction Ltd - Rome",  "status": "suspended",  "country": "IT",  "project_type": "safety"}
```

##### 404

[Section titled “404 ”](#404)

Project not found

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.