Material Item

A MaterialItem represents an individual item (or batch) of a material. For example, if the Material is “Safety Helmet Model X”, a MaterialItem is a specific helmet with its own serial number.

Belongs to a Material and to an office (via subtenant_id = office_id). Can be subject to actions on the compliance schedule (ActionSubscription with subscriber_type: PPE).

Use this API to:

Register individual items or batches of a material type
Get the material_item_id needed to create compliance schedule entries or certificates
Browse items of a material (filter by material_id)

Supports historicization.

Version: 2.0.0
OpenAPI version: 3.0.0

Authentication

OAuth2

Security scheme type: oauth2

Flow type: password

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

AccessToken

Security scheme type: apiKey

Query parameter name: access-token

Operations

index

POST

/v2/material-item/index

Returns a paginated list of material items.

Most useful filters:

material_id: all items of a specific material type
subtenant_id (office_id): all items in an office
name: search by name

Authorizations

OAuth2
AccessToken

Request Body

Parameters for searching material items

object

filter

object

material_item_id

Unique identifier. Used as subscriber_id (PPE) or resource_id.

string format: uuid

material_id

string format: uuid

code

string

name

string

description

string

serial

string

vendor

string

model

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

Available quantity (initial quantity minus items assigned via certificates).

integer

initial_quantity

Initial quantity of the item or batch.

integer

owned_active

Whether this item is currently active.

boolean

nullable

parent_active

Whether the parent entities are currently active.

boolean

nullable

per-page

integer

default: 100 >= 1

page

integer

default: 1 >= 1

sort

string

Allowed values: code name serial office_name project_name

history

If true, includes historicized entries.

boolean

Example

{
  "filter": {
    "material_id": "2a3b4c5d-6e7f-8901-abcd-ef2345678901"
  },
  "per-page": 20,
  "page": 1,
  "sort": "name"
}

Responses

200

List of material items

Array<object>

object

material_item_id

Unique identifier. Used as subscriber_id (PPE) or resource_id.

string format: uuid

material_id

string format: uuid

code

string

name

string

description

string

serial

string

vendor

string

model

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

Available quantity (initial quantity minus items assigned via certificates).

integer

initial_quantity

Initial quantity of the item or batch.

integer

owned_active

Whether this item is currently active.

boolean

nullable

parent_active

Whether the parent entities are currently active.

boolean

nullable

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

POST

/v2/material-item/create

Registers a new individual item or batch.

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

The Material must already exist (created via the Material API).

Authorizations

OAuth2
AccessToken

Request Body^required

Material item to register

object

material_item_id

Unique identifier. Auto-generated if not provided. Used as subscriber_id (with subscriber_type: PPE) in the compliance schedule and as resource_id in certificates.

string format: uuid

material_id

required

The material type this item belongs to. Pass the material_id from the Material API.

string format: uuid

code

Identifier code.

string

<= 50 characters

name

required

Name of the item.

string

<= 255 characters

description

Optional description.

string

nullable

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

data

Additional structured data in JSON format (may include initial quantity).

object

subtenant_id

required

The office this item belongs to. Pass the office_id.

string format: uuid

tenant_id

required

The project (company). Pass the project_id.

string format: uuid

Responses

201

Material item registered successfully

object

material_item_id

Unique identifier. Auto-generated if not provided. Used as subscriber_id (with subscriber_type: PPE) in the compliance schedule and as resource_id in certificates.

string format: uuid

material_id

required

The material type this item belongs to. Pass the material_id from the Material API.

string format: uuid

code

Identifier code.

string

<= 50 characters

name

required

Name of the item.

string

<= 255 characters

description

Optional description.

string

nullable

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

data

Additional structured data in JSON format (may include initial quantity).

object

subtenant_id

required

The office this item belongs to. Pass the office_id.

string format: uuid

tenant_id

required

The project (company). Pass the project_id.

string format: uuid

view

GET

/v2/material-item/view/{id}

Retrieves a single material item by its ID.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The material_item_id to retrieve.

Responses

200

Material item found

object

material_item_id

Unique identifier. Used as subscriber_id (PPE) or resource_id.

string format: uuid

material_id

string format: uuid

code

string

name

string

description

string

serial

string

vendor

string

model

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

Available quantity (initial quantity minus items assigned via certificates).

integer

initial_quantity

Initial quantity of the item or batch.

integer

owned_active

Whether this item is currently active.

boolean

nullable

parent_active

Whether the parent entities are currently active.

boolean

nullable

404

Material item not found

update

PUT

/v2/material-item/update/{id}

Updates an existing material item.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The material_item_id to update.

Request Body^required

Fields to update

object

material_item_id

Unique identifier. Auto-generated if not provided. Used as subscriber_id (with subscriber_type: PPE) in the compliance schedule and as resource_id in certificates.

string format: uuid

material_id

required

The material type this item belongs to. Pass the material_id from the Material API.

string format: uuid

code

Identifier code.

string

<= 50 characters

name

required

Name of the item.

string

<= 255 characters

description

Optional description.

string

nullable

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

data

Additional structured data in JSON format (may include initial quantity).

object

subtenant_id

required

The office this item belongs to. Pass the office_id.

string format: uuid

tenant_id

required

The project (company). Pass the project_id.

string format: uuid

Responses

200

Material item updated successfully

object

material_item_id

Unique identifier. Auto-generated if not provided. Used as subscriber_id (with subscriber_type: PPE) in the compliance schedule and as resource_id in certificates.

string format: uuid

material_id

required

The material type this item belongs to. Pass the material_id from the Material API.

string format: uuid

code

Identifier code.

string

<= 50 characters

name

required

Name of the item.

string

<= 255 characters

description

Optional description.

string

nullable

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

data

Additional structured data in JSON format (may include initial quantity).

object

subtenant_id

required

The office this item belongs to. Pass the office_id.

string format: uuid

tenant_id

required

The project (company). Pass the project_id.

string format: uuid

404

Material item not found

delete

DELETE

/v2/material-item/delete/{id}

Deletes a material item.

If force=false (default), the response lists child entities. If force=true, the item and all related entities are deleted.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The material_item_id to delete.

Query Parameters

force

boolean

If true, deletes the item and all child entities.

Responses

204

Material item deleted successfully

400

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

Material Item

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Request Body

Example

Responses

200

Headers

create

Authorizations

Request Body required

Responses

201

view

Authorizations

Path Parameters

Responses

200

404

update

Authorizations

Path Parameters

Request Body required

Responses

200

404

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

Request Body^required

Request Body^required