Skip to content
4HSE Developers DEV

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 ”

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

Request Body

Section titled “Request Body ”

Parameters for searching projects

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

List of projects

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

Request Body required

Section titled “Request Body required ”

Project object to be created

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

Project created successfully

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

Retrieves a single project by its ID.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The project_id to retrieve.

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Project found

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 ”

Project not found

delete

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

Path Parameters

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

The project_id to delete.

Query Parameters

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

Project scheduled for deletion

400
Section titled “400 ”

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

update

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

Path Parameters

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

The project_id to update.

Request Body required

Section titled “Request Body required ”

Project fields to update

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

Project updated successfully

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 ”

Project not found