---
title: "EntityAttachment"
url: "https://dev.4hse.com/api/entityattachment"
---

# EntityAttachment

An **EntityAttachment** links an uploaded file to an entity (certificate, action, office, person assignment, equipment, or any other entity on the platform).

Use this API to:

-   Link an uploaded file (via the Attachment API) to a certificate or other entity
-   Find all files linked to an entity (filter by `entity_id`)
-   Remove the link between a file and an entity

The file must already exist in the storage system (uploaded via the Attachment API). This endpoint does **not** upload files — it only creates the link.

The `attachment_id` field can be omitted: if only `attachment_path` is provided, the `attachment_id` is derived automatically from the path.

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-indexEntityAttachment-post)

POST

/v2/entity-attachment/index

-   

Returns a paginated list of files linked to an entity.

The `entity_id` parameter is required (as a query parameter or in the body). Returns all files linked to that specific entity.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Query Parameters

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

**entity\_id**

required

string format: uuid

The ID of the entity to retrieve linked files for. Required.

#### Request Body

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

Parameters for searching entity attachments

Select media typeapplication/json

object

**filter**

object

**entity\_attachment\_id**

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

**entity\_id**

required

The entity this file is linked to. Can be any entity on the platform:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

string format: uuid

**attachment\_id**

MD5 hash of the file path. Can be omitted on creation — derived automatically from `attachment_path`.

string

<= 50 characters

**attachment\_path**

required

Full path of the file in the storage system. The file must already exist (uploaded via the Attachment API).

string

<= 1024 characters

**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: attachment\_path

##### Example

```
{  "filter": {    "attachment_path": "fire-safety-certificate.pdf"  },  "per-page": 50,  "page": 1,  "sort": "attachment_path"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

List of entity attachments

Select media typeapplication/json

Array<object>

object

**entity\_attachment\_id**

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

**entity\_id**

required

The entity this file is linked to. Can be any entity on the platform:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

string format: uuid

**attachment\_id**

MD5 hash of the file path. Can be omitted on creation — derived automatically from `attachment_path`.

string

<= 50 characters

**attachment\_path**

required

Full path of the file in the storage system. The file must already exist (uploaded via the Attachment API).

string

<= 1024 characters

##### Example

```
[  {    "entity_attachment_id": "576331b6-fee8-4949-8bd9-d839202fb6e0",    "entity_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",    "attachment_id": "452b7448dce72057574d59f93d456ed0",    "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf"  }]
```

#### 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

### view

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

GET

/v2/entity-attachment/view/{id}

-   

Retrieves a single file-entity link by its ID.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The entity\_attachment\_id to retrieve.

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Entity attachment found

Select media typeapplication/json

object

**entity\_attachment\_id**

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

**entity\_id**

required

The entity this file is linked to. Can be any entity on the platform:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

string format: uuid

**attachment\_id**

MD5 hash of the file path. Can be omitted on creation — derived automatically from `attachment_path`.

string

<= 50 characters

**attachment\_path**

required

Full path of the file in the storage system. The file must already exist (uploaded via the Attachment API).

string

<= 1024 characters

##### Example

```
{  "entity_attachment_id": "576331b6-fee8-4949-8bd9-d839202fb6e0",  "entity_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",  "attachment_id": "452b7448dce72057574d59f93d456ed0",  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf"}
```

##### 404

[Section titled “404 ”](#404)

Entity attachment not found

### create

[Section titled “create”](#operation-createEntityAttachment-post)

POST

/v2/entity-attachment/create

-   

Creates a new link between an uploaded file and an entity.

Requires `entity_id` and `attachment_path`. The `attachment_id` can be omitted — it is derived automatically from the path. The `entity_attachment_id` is auto-generated if not provided.

The `entity_id` is the ID of the entity to link the file to. It can be any entity:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

The file must already exist (uploaded via the Attachment API). The combination of `entity_id` + `attachment_path` must be unique.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Request Body required

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

Entity attachment to create

Select media typeapplication/json

object

**entity\_attachment\_id**

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

**entity\_id**

required

The entity this file is linked to. Can be any entity on the platform:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

string format: uuid

**attachment\_id**

MD5 hash of the file path. Can be omitted on creation — derived automatically from `attachment_path`.

string

<= 50 characters

**attachment\_path**

required

Full path of the file in the storage system. The file must already exist (uploaded via the Attachment API).

string

<= 1024 characters

##### Example

```
{  "entity_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 201

[Section titled “201 ”](#201)

Entity attachment created successfully

Select media typeapplication/json

object

**entity\_attachment\_id**

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

**entity\_id**

required

The entity this file is linked to. Can be any entity on the platform:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

string format: uuid

**attachment\_id**

MD5 hash of the file path. Can be omitted on creation — derived automatically from `attachment_path`.

string

<= 50 characters

**attachment\_path**

required

Full path of the file in the storage system. The file must already exist (uploaded via the Attachment API).

string

<= 1024 characters

##### Example

```
{  "entity_attachment_id": "576331b6-fee8-4949-8bd9-d839202fb6e0",  "entity_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",  "attachment_id": "452b7448dce72057574d59f93d456ed0",  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/fire-safety-certificate.pdf"}
```

### update

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

PUT

/v2/entity-attachment/update/{id}

-   

Updates an existing file-entity link.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The entity\_attachment\_id to update.

#### Request Body required

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

Fields to update

Select media typeapplication/json

object

**entity\_attachment\_id**

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

**entity\_id**

required

The entity this file is linked to. Can be any entity on the platform:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

string format: uuid

**attachment\_id**

MD5 hash of the file path. Can be omitted on creation — derived automatically from `attachment_path`.

string

<= 50 characters

**attachment\_path**

required

Full path of the file in the storage system. The file must already exist (uploaded via the Attachment API).

string

<= 1024 characters

##### Example

```
{  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/updated-certificate.pdf"}
```

#### Responses

[Section titled “ Responses ”](#responses)

##### 200

[Section titled “200 ”](#200)

Entity attachment updated successfully

Select media typeapplication/json

object

**entity\_attachment\_id**

Unique identifier of the link. Auto-generated if not provided on creation.

string format: uuid

**entity\_id**

required

The entity this file is linked to. Can be any entity on the platform:

-   A `certificate_id` to attach a file to a certificate
-   An `action_id` to attach a file to an action
-   A `person_office_id` to attach a file to a person-office assignment
-   An `office_id`, `office_equipment_id`, `office_work_environment_id`, etc.

string format: uuid

**attachment\_id**

MD5 hash of the file path. Can be omitted on creation — derived automatically from `attachment_path`.

string

<= 50 characters

**attachment\_path**

required

Full path of the file in the storage system. The file must already exist (uploaded via the Attachment API).

string

<= 1024 characters

##### Example

```
{  "entity_attachment_id": "576331b6-fee8-4949-8bd9-d839202fb6e0",  "entity_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",  "attachment_path": "/projects/b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01/updated-certificate.pdf"}
```

##### 404

[Section titled “404 ”](#404)

Entity attachment not found

### delete

[Section titled “delete”](#operation-deleteEntityAttachment-delete)

DELETE

/v2/entity-attachment/delete/{id}

-   

Deletes a file-entity link. The file itself is not deleted — only the link.

If `force=false` (default), the response lists related entities. If `force=true`, the link is deleted.

## Authorizations

[Section titled “Authorizations ”](#authorizations)

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

#### Path Parameters

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

**id**

required

string format: uuid

The entity\_attachment\_id to delete.

#### Query Parameters

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

**force**

boolean

If true, deletes the link. If false, returns a preview of affected entities.

#### Responses

[Section titled “ Responses ”](#responses)

##### 204

[Section titled “204 ”](#204)

Entity attachment deleted successfully

##### 400

[Section titled “400 ”](#400)

Preview of affected entities (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.