Skip to content
4HSE Developers DEV

Material

A Material represents a type of material managed in an office. Each Material is a model/type, not a single physical item — individual items are tracked as MaterialItem entries.

Currently materials are only PPE (personal protective equipment, material_type: PPE), but other types may be added in the future.

Examples: “Safety Helmet Model X”, “Heat-Resistant Gloves Type Y”, “Fall Protection Harness”.

Belongs to an office (via subtenant_id = office_id).

Use this API to:

  • Register types of PPE available in an office
  • Get the material_id needed to create individual items (MaterialItem)
  • Browse the material inventory for an office (filter by subtenant_id)

Supports historicization.

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/material/index

Returns a paginated list of materials.

Most useful filters:

  • subtenant_id (office_id): all materials in a specific office
  • material_type: filter by type (currently only PPE)
  • name: search by name

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

Parameters for searching materials

object
filter
object
material_id
string format: uuid
material_type
string
Allowed values: PPE
code
string
name
string
description
string
category
string
data
object
subtenant_id
string format: uuid
tenant_id
string format: uuid
office_name

Name of the office.

string
project_name

Name of the project.

string
project_type
string
Allowed values: safety template
material_item_count

Number of available items (total minus items already assigned via certificates).

integer
owned_active

Whether this material is currently active.

boolean
nullable
parent_active

Whether the parent office is currently active.

boolean
nullable
per-page
integer
default: 100 >= 1
page
integer
default: 1 >= 1
sort
string
Allowed values: code name category material_type
history

If true, includes historicized entries.

boolean
Example
{
  "filter": {
    "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "material_type": "PPE"
  },
  "per-page": 20,
  "page": 1,
  "sort": "name"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

List of materials

Array<object>
object
material_id
string format: uuid
material_type
string
Allowed values: PPE
code
string
name
string
description
string
category
string
data
object
subtenant_id
string format: uuid
tenant_id
string format: uuid
office_name

Name of the office.

string
project_name

Name of the project.

string
project_type
string
Allowed values: safety template
material_item_count

Number of available items (total minus items already assigned via certificates).

integer
owned_active

Whether this material is currently active.

boolean
nullable
parent_active

Whether the parent office is currently active.

boolean
nullable

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/material/create

Registers a new material type in an office.

Requires material_type, subtenant_id (office_id), tenant_id (project_id), and name. The material_id is auto-generated if not provided.

After creating the material type, create MaterialItem entries for individual items or batches.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Material to register

object
material_id

Unique identifier of the material type. Auto-generated if not provided.

string format: uuid
material_type
required

Type of material. Currently only PPE (personal protective equipment). Other types may be added in the future.

string
<= 50 characters
Allowed values: PPE
code

Identifier code.

string
<= 50 characters
name
required

Name of the material type.

string
<= 255 characters
description

Optional description.

string
nullable
category

Material category.

string
<= 50 characters
data

Additional structured data in JSON format.

object
subtenant_id
required

The office this material belongs to. Pass the office_id.

string format: uuid
tenant_id
required

The project (company). Pass the project_id.

string format: uuid

Responses

Section titled “ Responses ”
201
Section titled “201 ”

Material registered successfully

object
material_id

Unique identifier of the material type. Auto-generated if not provided.

string format: uuid
material_type
required

Type of material. Currently only PPE (personal protective equipment). Other types may be added in the future.

string
<= 50 characters
Allowed values: PPE
code

Identifier code.

string
<= 50 characters
name
required

Name of the material type.

string
<= 255 characters
description

Optional description.

string
nullable
category

Material category.

string
<= 50 characters
data

Additional structured data in JSON format.

object
subtenant_id
required

The office this material belongs to. Pass the office_id.

string format: uuid
tenant_id
required

The project (company). Pass the project_id.

string format: uuid

view

Section titled “view”
GET
/v2/material/view/{id}

Retrieves a single material type by its ID.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The material_id to retrieve.

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Material found

object
material_id
string format: uuid
material_type
string
Allowed values: PPE
code
string
name
string
description
string
category
string
data
object
subtenant_id
string format: uuid
tenant_id
string format: uuid
office_name

Name of the office.

string
project_name

Name of the project.

string
project_type
string
Allowed values: safety template
material_item_count

Number of available items (total minus items already assigned via certificates).

integer
owned_active

Whether this material is currently active.

boolean
nullable
parent_active

Whether the parent office is currently active.

boolean
nullable
404
Section titled “404 ”

Material not found

update

Section titled “update”
PUT
/v2/material/update/{id}

Updates an existing material type.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The material_id to update.

Request Body required

Section titled “Request Body required ”

Fields to update

object
material_id

Unique identifier of the material type. Auto-generated if not provided.

string format: uuid
material_type
required

Type of material. Currently only PPE (personal protective equipment). Other types may be added in the future.

string
<= 50 characters
Allowed values: PPE
code

Identifier code.

string
<= 50 characters
name
required

Name of the material type.

string
<= 255 characters
description

Optional description.

string
nullable
category

Material category.

string
<= 50 characters
data

Additional structured data in JSON format.

object
subtenant_id
required

The office this material belongs to. Pass the office_id.

string format: uuid
tenant_id
required

The project (company). Pass the project_id.

string format: uuid

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Material updated successfully

object
material_id

Unique identifier of the material type. Auto-generated if not provided.

string format: uuid
material_type
required

Type of material. Currently only PPE (personal protective equipment). Other types may be added in the future.

string
<= 50 characters
Allowed values: PPE
code

Identifier code.

string
<= 50 characters
name
required

Name of the material type.

string
<= 255 characters
description

Optional description.

string
nullable
category

Material category.

string
<= 50 characters
data

Additional structured data in JSON format.

object
subtenant_id
required

The office this material belongs to. Pass the office_id.

string format: uuid
tenant_id
required

The project (company). Pass the project_id.

string format: uuid
404
Section titled “404 ”

Material not found

delete

Section titled “delete”
DELETE
/v2/material/delete/{id}

Deletes a material type.

If force=false (default), the response lists child entities (MaterialItem entries). If force=true, the material and all items are deleted.

Authorizations

Section titled “Authorizations ”

Path Parameters

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

The material_id to delete.

Query Parameters

Section titled “Query Parameters ”
force
boolean

If true, deletes the material and all child entities.

Responses

Section titled “ Responses ”
204
Section titled “204 ”

Material deleted successfully

400
Section titled “400 ”

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