---
title: "Material"
url: "https://dev.4hse.com/api/material"
---

# 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 ”](#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-indexMaterial-post)

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 ”](#authorizations)

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

#### Request Body

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

Parameters for searching materials

Select media typeapplication/json

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 ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of materials

Select media typeapplication/json

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 ”](#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-createMaterial-post)

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 ”](#authorizations)

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

#### Request Body required

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

Material to register

Select media typeapplication/json

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 ”](#responses)

##### 201

[Section titled “201 ”](#201)

Material registered successfully

Select media typeapplication/json

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”](#operation-viewMaterial-get)

GET

/v2/material/view/{id}

-   

Retrieves a single material type by its ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The material\_id to retrieve.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Material found

Select media typeapplication/json

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 ”](#404)

Material not found

### update

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

PUT

/v2/material/update/{id}

-   

Updates an existing material type.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The material\_id to update.

#### Request Body required

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

Fields to update

Select media typeapplication/json

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 ”](#responses)

##### 200

[Section titled “200 ”](#200)

Material updated successfully

Select media typeapplication/json

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 ”](#404)

Material not found

### delete

[Section titled “delete”](#operation-deleteMaterial-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 ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The material\_id to delete.

#### Query Parameters

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

**force**

boolean

If true, deletes the material and all child entities.

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Material deleted successfully

##### 400

[Section titled “400 ”](#400)

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

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.