Equipment

An Equipment represents a piece of equipment registered in an office (work location). Examples: forklift, scaffolding, crane, drill press.

Belongs to an office and can be subject to maintenance or check actions on the compliance schedule (ActionSubscription with subscriber_type: EQUIPMENT). Maintenance certificates reference the equipment via the resource_id field.

Use this API to:

Register equipment present in an office
Get the office_equipment_id needed to create compliance schedule entries or certificates
Browse the equipment inventory for an office (filter by office_id)

Supports historicization: when equipment or its parent office is historicized, the equipment and its child entities are excluded from normal queries.

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

Returns a paginated list of equipment.

Most useful filters:

office_id: all equipment in a specific office
name: search by name
project_id: all equipment in a company

Authorizations

OAuth2
AccessToken

Request Body

Parameters for searching equipment

object

filter

object

office_equipment_id

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

string format: uuid

office_id

string format: uuid

project_id

string format: uuid

equipment_id

string format: uuid

code

string

name

string

description

string

serial

string

vendor

string

model

string

office_name

Name of the office.

string

project_name

Name of the project (company).

string

project_type

string

Allowed values: safety template

category

Equipment category (from the catalog if linked).

string

owned_active

Whether this equipment 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

Field to sort by. Prefix with minus for descending order.

string

Allowed values: code name office_name project_name

history

If true, includes historicized (no longer active) entries. By default only current entries are returned.

boolean

Example

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

Responses

200

List of equipment

Array<object>

object

office_equipment_id

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

string format: uuid

office_id

string format: uuid

project_id

string format: uuid

equipment_id

string format: uuid

code

string

name

string

description

string

serial

string

vendor

string

model

string

office_name

Name of the office.

string

project_name

Name of the project (company).

string

project_type

string

Allowed values: safety template

category

Equipment category (from the catalog if linked).

string

owned_active

Whether this equipment is currently active.

boolean

nullable

parent_active

Whether the parent office is currently active.

boolean

nullable

Example

[
  {
    "office_equipment_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "code": "FL-001",
    "name": "Forklift A",
    "serial": "SN-2024-0001",
    "vendor": "Toyota",
    "model": "8FBN25",
    "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
    "office_name": "Rome North Site",
    "project_name": "Acme Construction Ltd",
    "project_type": "safety",
    "owned_active": true,
    "parent_active": true
  }
]

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

Registers a new piece of equipment in an office.

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

Authorizations

OAuth2
AccessToken

Request Body^required

Equipment to register

object

office_equipment_id

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

string format: uuid

office_id

required

The office this equipment belongs to. Pass the office_id from the Office API.

string format: uuid

equipment_id

Optional reference to an equipment model from the catalog (template).

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the equipment.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

Example

{
  "office_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "project_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "code": "FL-001",
  "name": "Forklift A",
  "serial": "SN-2024-0001",
  "vendor": "Toyota",
  "model": "8FBN25"
}

Responses

201

Equipment registered successfully

object

office_equipment_id

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

string format: uuid

office_id

required

The office this equipment belongs to. Pass the office_id from the Office API.

string format: uuid

equipment_id

Optional reference to an equipment model from the catalog (template).

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the equipment.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

view

GET

/v2/equipment/view/{id}

Retrieves a single equipment entry by its ID.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The office_equipment_id to retrieve.

Responses

200

Equipment found

object

office_equipment_id

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

string format: uuid

office_id

string format: uuid

project_id

string format: uuid

equipment_id

string format: uuid

code

string

name

string

description

string

serial

string

vendor

string

model

string

office_name

Name of the office.

string

project_name

Name of the project (company).

string

project_type

string

Allowed values: safety template

category

Equipment category (from the catalog if linked).

string

owned_active

Whether this equipment is currently active.

boolean

nullable

parent_active

Whether the parent office is currently active.

boolean

nullable

404

Equipment not found

update

PUT

/v2/equipment/update/{id}

Updates an existing equipment entry.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The office_equipment_id to update.

Request Body^required

Fields to update

object

office_equipment_id

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

string format: uuid

office_id

required

The office this equipment belongs to. Pass the office_id from the Office API.

string format: uuid

equipment_id

Optional reference to an equipment model from the catalog (template).

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the equipment.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

Example

{
  "name": "Forklift A - Revised",
  "serial": "SN-2024-0001-R"
}

Responses

200

Equipment updated successfully

object

office_equipment_id

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

string format: uuid

office_id

required

The office this equipment belongs to. Pass the office_id from the Office API.

string format: uuid

equipment_id

Optional reference to an equipment model from the catalog (template).

string format: uuid

code

Identifier code.

string

<= 45 characters

name

required

Name of the equipment.

string

<= 255 characters

description

Optional description.

string

nullable

project_id

required

The project (company). Pass the project_id.

string format: uuid

serial

Serial number.

string

<= 50 characters

vendor

Manufacturer.

string

<= 50 characters

model

Model name.

string

<= 50 characters

404

Equipment not found

delete

DELETE

/v2/equipment/delete/{id}

Deletes an equipment entry.

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

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The office_equipment_id to delete.

Query Parameters

force

boolean

If true, deletes the equipment and all child entities. If false, returns a preview of affected entities.

Equipment

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Request Body

Example

Responses

200

Example

Headers

create

Authorizations

Request Body^required

Example

Responses

201

view

Authorizations

Path Parameters

Responses

200

404

update

Authorizations

Path Parameters

Request Body^required

Example

Responses

200

404

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

Equipment

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Request Body

Example

Responses

200

Example

Headers

create

Authorizations

Request Body required

Example

Responses

201

view

Authorizations

Path Parameters

Responses

200

404

update

Authorizations

Path Parameters

Request Body required

Example

Responses

200

404

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

Request Body^required

Request Body^required