Substance

A Substance represents a hazardous or chemical substance registered in an office. Examples: solvents, acids, powders, compressed gases.

Belongs to an office and can be subject to check actions on the compliance schedule (ActionSubscription with subscriber_type: SUBSTANCE).

Use this API to:

• Register substances present in an office
• Get the office_substance_id needed to create compliance schedule entries or certificates
• Browse the substance inventory for an office (filter by office_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/substance/index

Returns a paginated list of substances.

Most useful filters:

• office_id: all substances in a specific office
• name: search by name

Authorizations

• OAuth2
• AccessToken

Request Body

Parameters for searching substances

object

filter

object

office_substance_id

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

string format: uuid

office_id

string format: uuid

project_id

string format: uuid

code

string

name

string

description

string

office_name

Name of the office.

string

project_name

Name of the project.

string

project_type

string

Allowed values: safety template

owned_active

Whether this substance 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 office_name project_name

history

If true, includes historicized entries.

boolean

Example

{
  "filter": {
    "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "per-page": 20,
  "page": 1,
  "sort": "name"
}

Responses

200

List of substances

Array<object>

object

office_substance_id

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

string format: uuid

office_id

string format: uuid

project_id

string format: uuid

code

string

name

string

description

string

office_name

Name of the office.

string

project_name

Name of the project.

string

project_type

string

Allowed values: safety template

owned_active

Whether this substance is currently active.

boolean

nullable

parent_active

Whether the parent office is 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/substance/create

Registers a new substance in an office.

Requires office_id, project_id, and name. The office_substance_id is auto-generated if not provided.

Authorizations

• OAuth2
• AccessToken

Request Body ^required

Substance to register

object

office_substance_id

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

string format: uuid

office_id

required

The office this substance belongs to. Pass the office_id.

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the substance.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

Responses

201

Substance registered successfully

object

office_substance_id

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

string format: uuid

office_id

required

The office this substance belongs to. Pass the office_id.

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the substance.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

view

GET

/v2/substance/view/{id}

Retrieves a single substance by its ID.

Authorizations

• OAuth2
• AccessToken

Path Parameters

id

required

string format: uuid

The office_substance_id to retrieve.

Responses

200

Substance found

object

office_substance_id

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

string format: uuid

office_id

string format: uuid

project_id

string format: uuid

code

string

name

string

description

string

office_name

Name of the office.

string

project_name

Name of the project.

string

project_type

string

Allowed values: safety template

owned_active

Whether this substance is currently active.

boolean

nullable

parent_active

Whether the parent office is currently active.

boolean

nullable

404

Substance not found

update

PUT

/v2/substance/update/{id}

Updates an existing substance.

Authorizations

• OAuth2
• AccessToken

Path Parameters

id

required

string format: uuid

The office_substance_id to update.

Request Body ^required

Fields to update

object

office_substance_id

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

string format: uuid

office_id

required

The office this substance belongs to. Pass the office_id.

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the substance.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

Responses

200

Substance updated successfully

object

office_substance_id

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

string format: uuid

office_id

required

The office this substance belongs to. Pass the office_id.

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the substance.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

404

Substance not found

delete

DELETE

/v2/substance/delete/{id}

Deletes a substance.

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

Authorizations

• OAuth2
• AccessToken

Path Parameters

id

required

string format: uuid

The office_substance_id to delete.

Query Parameters

force

boolean

If true, deletes the substance and all child entities.

Responses

204

Substance deleted successfully

400

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