---
title: "Equipment"
url: "https://dev.4hse.com/api/equipment"
---

# 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

[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-indexEquipment-post)

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

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body

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

Parameters for searching equipment

Select media typeapplication/json

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

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of equipment

Select media typeapplication/json

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

[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-createEquipment-post)

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

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body required

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

Equipment to register

Select media typeapplication/json

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

[Section titled “ Responses ”](#responses)

##### 201

[Section titled “201 ”](#201)

Equipment registered successfully

Select media typeapplication/json

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

[Section titled “view”](#operation-viewEquipment-get)

GET

/v2/equipment/view/{id}

-   

Retrieves a single equipment entry by its ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The office\_equipment\_id to retrieve.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Equipment found

Select media typeapplication/json

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

[Section titled “404 ”](#404)

Equipment not found

### update

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

PUT

/v2/equipment/update/{id}

-   

Updates an existing equipment entry.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The office\_equipment\_id to update.

#### Request Body required

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

Fields to update

Select media typeapplication/json

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

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Equipment updated successfully

Select media typeapplication/json

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

[Section titled “404 ”](#404)

Equipment not found

### delete

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

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The office\_equipment\_id to delete.

#### Query Parameters

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

**force**

boolean

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

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Equipment 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.