Skip to content
4HSE Developers DEV

EntityEmployee

An EntityEmployee represents the assignment of a person to an office resource: a safety role, a piece of equipment, a work environment, or a substance.

For example: assigning “John Smith” to the role “Safety Officer” or to the equipment “Forklift A”.

The entity_id field contains the resource ID and the type field specifies its kind:

  • ROLE: a safety organization role (office_role_id)
  • EQUIPMENT: a piece of equipment (office_equipment_id)
  • WORK_ENVIRONMENT: a work environment (office_work_environment_id)
  • SUBSTANCE: a substance (office_substance_id)

Use this API to:

  • Assign a person to a role, equipment, work environment, or substance
  • Find all people assigned to a resource (filter by entity_id)
  • Find all resources a person is assigned to (filter by person_office_id)

Supports historicization.

Version
2.0.0
OpenAPI version
3.0.0

Authentication

Section titled “ Authentication ”

OAuth2

Section titled “OAuth2 ”

Security scheme type: oauth2

Flow type: password

Token URL: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token

AccessToken

Section titled “AccessToken ”

Security scheme type: apiKey

Query parameter name: access-token

Operations

Section titled “Operations”

index

Section titled “index”
POST
/v2/entity-employee/index

Returns a paginated list of person-resource assignments.

Most useful filters:

  • entity_id: all people assigned to a specific resource
  • person_office_id: all resources a person is assigned to
  • type: filter by resource type (ROLE, EQUIPMENT, WORK_ENVIRONMENT, SUBSTANCE)
  • office_id: all assignments in an office

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”

Parameters for searching

object
filter
object
entity_employee_id
string format: uuid
entity_id
string format: uuid
person_office_id
string format: uuid
type
string
Allowed values: EQUIPMENT WORK_ENVIRONMENT SUBSTANCE ROLE
office_id
string format: uuid
project_id
string format: uuid
person_id

The person ID.

string format: uuid
person_code

Employee code.

string
person_first_name
string
person_last_name
string
person_is_external

Whether the person is external prevention staff.

boolean
entity_code

Code of the assigned resource.

string
entity_name

Name of the assigned resource.

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 assignment is currently active.

boolean
nullable
parent_active

Whether the parent entities are currently active.

boolean
nullable
per-page
integer
default: 100 >= 1
page
integer
default: 1 >= 1
sort
string
Allowed values: person_code person_first_name person_last_name entity_code entity_name type
history

If true, includes historicized entries.

boolean
Example
{
  "filter": {
    "entity_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "type": "ROLE"
  },
  "per-page": 20,
  "page": 1,
  "sort": "person_last_name"
}

Responses

Section titled “ Responses ”
200
Section titled “200 ”

List of person-resource assignments

Array<object>
object
entity_employee_id
string format: uuid
entity_id
string format: uuid
person_office_id
string format: uuid
type
string
Allowed values: EQUIPMENT WORK_ENVIRONMENT SUBSTANCE ROLE
office_id
string format: uuid
project_id
string format: uuid
person_id

The person ID.

string format: uuid
person_code

Employee code.

string
person_first_name
string
person_last_name
string
person_is_external

Whether the person is external prevention staff.

boolean
entity_code

Code of the assigned resource.

string
entity_name

Name of the assigned resource.

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 assignment is currently active.

boolean
nullable
parent_active

Whether the parent entities are currently active.

boolean
nullable

Headers

Section titled “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”
POST
/v2/entity-employee/create

Assigns a person to a resource.

Requires entity_id, person_office_id, office_id, and project_id. The entity_employee_id is auto-generated if not provided.

What to pass as entity_id depends on the type:

  • ROLE: pass the office_role_id
  • EQUIPMENT: pass the office_equipment_id
  • WORK_ENVIRONMENT: pass the office_work_environment_id
  • SUBSTANCE: pass the office_substance_id

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”

Assignment to create

object
entity_employee_id

Unique identifier. Auto-generated if not provided.

string format: uuid
entity_id
required

The resource this person is assigned to. What to pass depends on type:

  • ROLE: pass the office_role_id
  • EQUIPMENT: pass the office_equipment_id
  • WORK_ENVIRONMENT: pass the office_work_environment_id
  • SUBSTANCE: pass the office_substance_id
string format: uuid
person_office_id
required

The person-office assignment. Pass the person_office_id from the PersonOffice API.

string format: uuid
type

Type of resource:

  • ROLE: a safety organization role
  • EQUIPMENT: a piece of equipment
  • WORK_ENVIRONMENT: a work environment
  • SUBSTANCE: a substance
string
<= 50 characters
Allowed values: EQUIPMENT WORK_ENVIRONMENT SUBSTANCE ROLE
office_id
required

The office. Pass the office_id.

string format: uuid
project_id
required

The project (company). Pass the project_id.

string format: uuid

Responses

Section titled “ Responses ”
201
Section titled “201 ”

Assignment created successfully

object
entity_employee_id

Unique identifier. Auto-generated if not provided.

string format: uuid
entity_id
required

The resource this person is assigned to. What to pass depends on type:

  • ROLE: pass the office_role_id
  • EQUIPMENT: pass the office_equipment_id
  • WORK_ENVIRONMENT: pass the office_work_environment_id
  • SUBSTANCE: pass the office_substance_id
string format: uuid
person_office_id
required

The person-office assignment. Pass the person_office_id from the PersonOffice API.

string format: uuid
type

Type of resource:

  • ROLE: a safety organization role
  • EQUIPMENT: a piece of equipment
  • WORK_ENVIRONMENT: a work environment
  • SUBSTANCE: a substance
string
<= 50 characters
Allowed values: EQUIPMENT WORK_ENVIRONMENT SUBSTANCE ROLE
office_id
required

The office. Pass the office_id.

string format: uuid
project_id
required

The project (company). Pass the project_id.

string format: uuid

view

Section titled “view”
GET
/v2/entity-employee/view/{id}

Retrieves a single assignment by its ID.

Authorizations

Section titled “Authorizations ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

The entity_employee_id to retrieve.

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Assignment found

object
entity_employee_id
string format: uuid
entity_id
string format: uuid
person_office_id
string format: uuid
type
string
Allowed values: EQUIPMENT WORK_ENVIRONMENT SUBSTANCE ROLE
office_id
string format: uuid
project_id
string format: uuid
person_id

The person ID.

string format: uuid
person_code

Employee code.

string
person_first_name
string
person_last_name
string
person_is_external

Whether the person is external prevention staff.

boolean
entity_code

Code of the assigned resource.

string
entity_name

Name of the assigned resource.

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 assignment is currently active.

boolean
nullable
parent_active

Whether the parent entities are currently active.

boolean
nullable
404
Section titled “404 ”

Assignment not found

update

Section titled “update”
PUT
/v2/entity-employee/update/{id}

Updates an existing assignment.

Authorizations

Section titled “Authorizations ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

The entity_employee_id to update.

Request Body required

Section titled “Request Body required ”

Fields to update

object
entity_employee_id

Unique identifier. Auto-generated if not provided.

string format: uuid
entity_id
required

The resource this person is assigned to. What to pass depends on type:

  • ROLE: pass the office_role_id
  • EQUIPMENT: pass the office_equipment_id
  • WORK_ENVIRONMENT: pass the office_work_environment_id
  • SUBSTANCE: pass the office_substance_id
string format: uuid
person_office_id
required

The person-office assignment. Pass the person_office_id from the PersonOffice API.

string format: uuid
type

Type of resource:

  • ROLE: a safety organization role
  • EQUIPMENT: a piece of equipment
  • WORK_ENVIRONMENT: a work environment
  • SUBSTANCE: a substance
string
<= 50 characters
Allowed values: EQUIPMENT WORK_ENVIRONMENT SUBSTANCE ROLE
office_id
required

The office. Pass the office_id.

string format: uuid
project_id
required

The project (company). Pass the project_id.

string format: uuid

Responses

Section titled “ Responses ”
200
Section titled “200 ”

Assignment updated successfully

object
entity_employee_id

Unique identifier. Auto-generated if not provided.

string format: uuid
entity_id
required

The resource this person is assigned to. What to pass depends on type:

  • ROLE: pass the office_role_id
  • EQUIPMENT: pass the office_equipment_id
  • WORK_ENVIRONMENT: pass the office_work_environment_id
  • SUBSTANCE: pass the office_substance_id
string format: uuid
person_office_id
required

The person-office assignment. Pass the person_office_id from the PersonOffice API.

string format: uuid
type

Type of resource:

  • ROLE: a safety organization role
  • EQUIPMENT: a piece of equipment
  • WORK_ENVIRONMENT: a work environment
  • SUBSTANCE: a substance
string
<= 50 characters
Allowed values: EQUIPMENT WORK_ENVIRONMENT SUBSTANCE ROLE
office_id
required

The office. Pass the office_id.

string format: uuid
project_id
required

The project (company). Pass the project_id.

string format: uuid
404
Section titled “404 ”

Assignment not found

delete

Section titled “delete”
DELETE
/v2/entity-employee/delete/{id}

Deletes a person-resource assignment.

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

Authorizations

Section titled “Authorizations ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

The entity_employee_id to delete.

Query Parameters

Section titled “Query Parameters ”
force
boolean

If true, deletes the assignment and all child entities.

Responses

Section titled “ Responses ”
204
Section titled “204 ”

Assignment deleted successfully

400
Section titled “400 ”

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