--- title: "Action" url: "https://dev.4hse.com/api/action" --- # Action An **Action** represents a preventive safety action defined within an office. Each action describes a compliance requirement: a training course, a medical examination, equipment maintenance, PPE provision, or an operational check procedure. **Hierarchy:** Project (company) → Office (work location) → Action (compliance requirement). Actions are the link between compliance requirements and the compliance schedule: - **ActionSubscription** (compliance schedule) records who must do what, linking an action to a person, equipment, work environment, substance, role, work group, office, PPE, or supplier - **CertificateAction** links a certificate to an action, proving the requirement has been fulfilled Use this API to: - Find actions defined in an office (filter by `subtenant_id` with the `office_id`) - Find actions by type (e.g. `action_type: TRAINING` for training courses) - Create new preventive actions within an office - Get the `action_id` needed to create compliance schedule entries or link certificates Action types (`action_type`): - `TRAINING`: training courses — applies to people - `HEALTH`: medical surveillance — applies to people - `PER`: personal protective equipment (PPE) — applies to people - `CHECK`: check procedures and checklists — applies to people, equipment, work environments, substances, roles, work groups, PPE, offices, suppliers - `MAINTENANCE`: maintenance — applies to equipment, work environments, PPE, offices The `action_type` field **cannot be changed** after creation. 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-indexAction-post) POST /v2/action/index - Returns a paginated list of actions. Most useful filters: - `subtenant_id` (office\_id) + `action_type`: find all actions of a type in an office (e.g. all training courses at a construction site) - `tenant_id` (project\_id) + `action_type`: find all actions of a type in the company - `name`: search an action by name The response includes compliance counts: - `countSubscribed`: total number of subscribed resources - `countValid`: number with a valid certificate - `countScheduled`: number with a scheduled future session - `countToDo`: number without a valid certificate or scheduled session — the compliance gaps to resolve ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/action/#oauth2)** - **[AccessToken](/api/action/#accesstoken)** #### Request Body [Section titled “Request Body ”](#request-body) Parameters for searching actions Select media typeapplication/json object **filter** object **action\_id** Unique identifier of the action. string format: uuid **action\_type** Type of preventive action. See Action schema for details. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **code** Identifier code for the action. string **name** Descriptive name of the action. string **description** Optional detailed description. string **validity\_unit** Unit for the certificate validity period. string Allowed values: YEAR MONTH DAY **validity** Number of validity units. integer **expire\_interval** Days before expiration to trigger EXPIRING status. integer **manager** Action managers (JSON). string format: json **assignee** Action assignees (JSON). string format: json **watcher** Action watchers (JSON). string format: json **subscriber\_type** JSON array of allowed subscriber types. If null, determined by `action_type`. string format: json nullable **data** Additional structured data. string format: json **subtenant\_id** The office (work location) where this action is defined. string format: uuid **tenant\_id** The project (company) this action belongs to. string format: uuid **countSubscribed** Total number of resources subscribed to this action. integer **countValid** Number of subscribed resources with a currently valid certificate. integer **countScheduled** Number of subscribed resources with a scheduled future session. integer **countToDo** Number of subscribed resources without a valid certificate or scheduled session — compliance gaps to resolve. integer **office\_name** Name of the office where this action is defined. string **project\_name** Name of the project (company). string **project\_type** Type of the parent project. string **owned\_active** Whether this action is currently active in its validity period. 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 (e.g. “-name”). string Allowed values: code name action\_type office\_name project\_name **history** If true, includes historicized (no longer active) entries in the results. By default only current entries are returned. boolean ##### Example ``` { "filter": { "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "action_type": "TRAINING" }, "per-page": 20, "page": 1, "sort": "name"} ``` #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) List of actions Select media typeapplication/json Array object **action\_id** Unique identifier of the action. string format: uuid **action\_type** Type of preventive action. See Action schema for details. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **code** Identifier code for the action. string **name** Descriptive name of the action. string **description** Optional detailed description. string **validity\_unit** Unit for the certificate validity period. string Allowed values: YEAR MONTH DAY **validity** Number of validity units. integer **expire\_interval** Days before expiration to trigger EXPIRING status. integer **manager** Action managers (JSON). string format: json **assignee** Action assignees (JSON). string format: json **watcher** Action watchers (JSON). string format: json **subscriber\_type** JSON array of allowed subscriber types. If null, determined by `action_type`. string format: json nullable **data** Additional structured data. string format: json **subtenant\_id** The office (work location) where this action is defined. string format: uuid **tenant\_id** The project (company) this action belongs to. string format: uuid **countSubscribed** Total number of resources subscribed to this action. integer **countValid** Number of subscribed resources with a currently valid certificate. integer **countScheduled** Number of subscribed resources with a scheduled future session. integer **countToDo** Number of subscribed resources without a valid certificate or scheduled session — compliance gaps to resolve. integer **office\_name** Name of the office where this action is defined. string **project\_name** Name of the project (company). string **project\_type** Type of the parent project. string **owned\_active** Whether this action is currently active in its validity period. boolean nullable **parent\_active** Whether the parent office is currently active. boolean nullable ##### Example ``` [ { "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "action_type": "TRAINING", "code": "FST-01", "name": "Fire Safety Training Medium Risk", "description": "Mandatory fire safety course for medium risk workers", "validity_unit": "YEAR", "validity": 5, "expire_interval": 90, "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01", "office_name": "Rome North Site", "project_name": "Acme Construction Ltd", "countSubscribed": 25, "countValid": 18, "countScheduled": 3, "countToDo": 4, "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-createAction-post) POST /v2/action/create - Creates a new action within an office. Requires `action_type`, `name`, `subtenant_id` (office\_id), and `tenant_id` (project\_id). The `action_id` is auto-generated if not provided. Creating an action does **not** automatically create compliance schedule entries. To assign people, equipment, or other resources to this action, create ActionSubscription entries separately. The `validity` + `validity_unit` fields define how long certificates linked to this action remain valid (e.g. `validity: 5`, `validity_unit: YEAR` = certificates expire 5 years after issue). The `subscriber_type` field restricts which resource types can be subscribed to this action. If not specified, the allowed types are determined by the `action_type`. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/action/#oauth2)** - **[AccessToken](/api/action/#accesstoken)** #### Request Body required [Section titled “Request Body required ”](#request-body) Action object to be created Select media typeapplication/json object **action\_id** Unique identifier of the action. Auto-generated if not provided on creation. Compliance schedule entries (ActionSubscription) and certificate links (CertificateAction) reference the action via this field. string format: uuid **action\_type** required Type of preventive action: - `TRAINING`: training courses — applies to people - `HEALTH`: medical surveillance — applies to people - `PER`: personal protective equipment — applies to people - `CHECK`: check procedures — applies to people, equipment, work environments, substances, roles, work groups, PPE, offices, suppliers - `MAINTENANCE`: maintenance — applies to equipment, work environments, PPE, offices Cannot be changed after creation. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **code** Identifier code for the action. string <= 50 characters **name** required Descriptive name of the action. string <= 255 characters **description** Optional detailed description. string **validity\_unit** Unit for the certificate validity period. Used together with `validity`. string Allowed values: YEAR MONTH DAY **validity** Number of validity units. Together with `validity_unit`, defines how long certificates linked to this action remain valid (e.g. validity 5 + validity\_unit YEAR = 5 years). integer **expire\_interval** Number of days before expiration to trigger the EXPIRING status in the compliance schedule. Subscriptions transition from VALID to EXPIRING this many days before the certificate expires. integer **manager** Action managers (JSON). string format: json **assignee** Action assignees (JSON). string format: json **watcher** Action watchers (JSON). string format: json **subscriber\_type** JSON array of resource types that can be subscribed to this action. Possible values: PERSON, ROLE, WORK\_GROUP, WORK\_ENVIRONMENT, SUBSTANCE, EQUIPMENT, OFFICE, PPE, UNIT. If null, the allowed types are determined by the `action_type`. string format: json nullable **data** Additional structured data in JSON format. string format: json **subtenant\_id** required The office (work location) where this action is defined. Pass the `office_id` obtained from the Office API. string format: uuid **tenant\_id** required The project (company) this action belongs to. Pass the `project_id` obtained from the Project API. string format: uuid ##### Example ``` { "action_type": "TRAINING", "code": "FST-01", "name": "Fire Safety Training Medium Risk", "description": "Mandatory fire safety course for medium risk workers", "validity_unit": "YEAR", "validity": 5, "expire_interval": 90, "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"} ``` #### Responses [Section titled “ Responses ”](#responses) ##### 201 [Section titled “201 ”](#201) Action created successfully Select media typeapplication/json object **action\_id** Unique identifier of the action. Auto-generated if not provided on creation. Compliance schedule entries (ActionSubscription) and certificate links (CertificateAction) reference the action via this field. string format: uuid **action\_type** required Type of preventive action: - `TRAINING`: training courses — applies to people - `HEALTH`: medical surveillance — applies to people - `PER`: personal protective equipment — applies to people - `CHECK`: check procedures — applies to people, equipment, work environments, substances, roles, work groups, PPE, offices, suppliers - `MAINTENANCE`: maintenance — applies to equipment, work environments, PPE, offices Cannot be changed after creation. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **code** Identifier code for the action. string <= 50 characters **name** required Descriptive name of the action. string <= 255 characters **description** Optional detailed description. string **validity\_unit** Unit for the certificate validity period. Used together with `validity`. string Allowed values: YEAR MONTH DAY **validity** Number of validity units. Together with `validity_unit`, defines how long certificates linked to this action remain valid (e.g. validity 5 + validity\_unit YEAR = 5 years). integer **expire\_interval** Number of days before expiration to trigger the EXPIRING status in the compliance schedule. Subscriptions transition from VALID to EXPIRING this many days before the certificate expires. integer **manager** Action managers (JSON). string format: json **assignee** Action assignees (JSON). string format: json **watcher** Action watchers (JSON). string format: json **subscriber\_type** JSON array of resource types that can be subscribed to this action. Possible values: PERSON, ROLE, WORK\_GROUP, WORK\_ENVIRONMENT, SUBSTANCE, EQUIPMENT, OFFICE, PPE, UNIT. If null, the allowed types are determined by the `action_type`. string format: json nullable **data** Additional structured data in JSON format. string format: json **subtenant\_id** required The office (work location) where this action is defined. Pass the `office_id` obtained from the Office API. string format: uuid **tenant\_id** required The project (company) this action belongs to. Pass the `project_id` obtained from the Project API. string format: uuid ##### Example ``` { "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "action_type": "TRAINING", "code": "FST-01", "name": "Fire Safety Training Medium Risk", "validity_unit": "YEAR", "validity": 5, "expire_interval": 90, "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"} ``` ### view [Section titled “view”](#operation-viewAction-get) GET /v2/action/view/{id} - Retrieves a single action by its ID. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/action/#oauth2)** - **[AccessToken](/api/action/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The action\_id to retrieve. #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Action found Select media typeapplication/json object **action\_id** Unique identifier of the action. string format: uuid **action\_type** Type of preventive action. See Action schema for details. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **code** Identifier code for the action. string **name** Descriptive name of the action. string **description** Optional detailed description. string **validity\_unit** Unit for the certificate validity period. string Allowed values: YEAR MONTH DAY **validity** Number of validity units. integer **expire\_interval** Days before expiration to trigger EXPIRING status. integer **manager** Action managers (JSON). string format: json **assignee** Action assignees (JSON). string format: json **watcher** Action watchers (JSON). string format: json **subscriber\_type** JSON array of allowed subscriber types. If null, determined by `action_type`. string format: json nullable **data** Additional structured data. string format: json **subtenant\_id** The office (work location) where this action is defined. string format: uuid **tenant\_id** The project (company) this action belongs to. string format: uuid **countSubscribed** Total number of resources subscribed to this action. integer **countValid** Number of subscribed resources with a currently valid certificate. integer **countScheduled** Number of subscribed resources with a scheduled future session. integer **countToDo** Number of subscribed resources without a valid certificate or scheduled session — compliance gaps to resolve. integer **office\_name** Name of the office where this action is defined. string **project\_name** Name of the project (company). string **project\_type** Type of the parent project. string **owned\_active** Whether this action is currently active in its validity period. boolean nullable **parent\_active** Whether the parent office is currently active. boolean nullable ##### Example ``` { "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "action_type": "TRAINING", "code": "FST-01", "name": "Fire Safety Training Medium Risk", "validity_unit": "YEAR", "validity": 5, "expire_interval": 90, "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01", "office_name": "Rome North Site", "project_name": "Acme Construction Ltd", "countSubscribed": 25, "countValid": 18, "countScheduled": 3, "countToDo": 4, "owned_active": true, "parent_active": true} ``` ##### 404 [Section titled “404 ”](#404) Action not found ### update [Section titled “update”](#operation-updateAction-put) PUT /v2/action/update/{id} - Updates an existing action. The `action_type` field **cannot be changed** after creation. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/action/#oauth2)** - **[AccessToken](/api/action/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The action\_id to update. #### Request Body required [Section titled “Request Body required ”](#request-body) Action fields to update Select media typeapplication/json object **action\_id** Unique identifier of the action. Auto-generated if not provided on creation. Compliance schedule entries (ActionSubscription) and certificate links (CertificateAction) reference the action via this field. string format: uuid **action\_type** required Type of preventive action: - `TRAINING`: training courses — applies to people - `HEALTH`: medical surveillance — applies to people - `PER`: personal protective equipment — applies to people - `CHECK`: check procedures — applies to people, equipment, work environments, substances, roles, work groups, PPE, offices, suppliers - `MAINTENANCE`: maintenance — applies to equipment, work environments, PPE, offices Cannot be changed after creation. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **code** Identifier code for the action. string <= 50 characters **name** required Descriptive name of the action. string <= 255 characters **description** Optional detailed description. string **validity\_unit** Unit for the certificate validity period. Used together with `validity`. string Allowed values: YEAR MONTH DAY **validity** Number of validity units. Together with `validity_unit`, defines how long certificates linked to this action remain valid (e.g. validity 5 + validity\_unit YEAR = 5 years). integer **expire\_interval** Number of days before expiration to trigger the EXPIRING status in the compliance schedule. Subscriptions transition from VALID to EXPIRING this many days before the certificate expires. integer **manager** Action managers (JSON). string format: json **assignee** Action assignees (JSON). string format: json **watcher** Action watchers (JSON). string format: json **subscriber\_type** JSON array of resource types that can be subscribed to this action. Possible values: PERSON, ROLE, WORK\_GROUP, WORK\_ENVIRONMENT, SUBSTANCE, EQUIPMENT, OFFICE, PPE, UNIT. If null, the allowed types are determined by the `action_type`. string format: json nullable **data** Additional structured data in JSON format. string format: json **subtenant\_id** required The office (work location) where this action is defined. Pass the `office_id` obtained from the Office API. string format: uuid **tenant\_id** required The project (company) this action belongs to. Pass the `project_id` obtained from the Project API. string format: uuid ##### Example ``` { "name": "Fire Safety Training High Risk", "validity": 3} ``` #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Action updated successfully Select media typeapplication/json object **action\_id** Unique identifier of the action. Auto-generated if not provided on creation. Compliance schedule entries (ActionSubscription) and certificate links (CertificateAction) reference the action via this field. string format: uuid **action\_type** required Type of preventive action: - `TRAINING`: training courses — applies to people - `HEALTH`: medical surveillance — applies to people - `PER`: personal protective equipment — applies to people - `CHECK`: check procedures — applies to people, equipment, work environments, substances, roles, work groups, PPE, offices, suppliers - `MAINTENANCE`: maintenance — applies to equipment, work environments, PPE, offices Cannot be changed after creation. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **code** Identifier code for the action. string <= 50 characters **name** required Descriptive name of the action. string <= 255 characters **description** Optional detailed description. string **validity\_unit** Unit for the certificate validity period. Used together with `validity`. string Allowed values: YEAR MONTH DAY **validity** Number of validity units. Together with `validity_unit`, defines how long certificates linked to this action remain valid (e.g. validity 5 + validity\_unit YEAR = 5 years). integer **expire\_interval** Number of days before expiration to trigger the EXPIRING status in the compliance schedule. Subscriptions transition from VALID to EXPIRING this many days before the certificate expires. integer **manager** Action managers (JSON). string format: json **assignee** Action assignees (JSON). string format: json **watcher** Action watchers (JSON). string format: json **subscriber\_type** JSON array of resource types that can be subscribed to this action. Possible values: PERSON, ROLE, WORK\_GROUP, WORK\_ENVIRONMENT, SUBSTANCE, EQUIPMENT, OFFICE, PPE, UNIT. If null, the allowed types are determined by the `action_type`. string format: json nullable **data** Additional structured data in JSON format. string format: json **subtenant\_id** required The office (work location) where this action is defined. Pass the `office_id` obtained from the Office API. string format: uuid **tenant\_id** required The project (company) this action belongs to. Pass the `project_id` obtained from the Project API. string format: uuid ##### Example ``` { "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "action_type": "TRAINING", "name": "Fire Safety Training High Risk", "validity": 3, "validity_unit": "YEAR"} ``` ##### 404 [Section titled “404 ”](#404) Action not found ### delete [Section titled “delete”](#operation-deleteAction-delete) DELETE /v2/action/delete/{id} - Deletes an action. If `force=false` (default), the response lists child entities (subscriptions, sessions, linked certificates). If `force=true`, the action and all related entities are deleted. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/action/#oauth2)** - **[AccessToken](/api/action/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The action\_id to delete. #### Query Parameters [Section titled “Query Parameters ”](#query-parameters) **force** boolean If true, deletes the action and all child entities. If false, returns a preview of affected entities. #### Responses [Section titled “ Responses ”](#responses) ##### 204 [Section titled “204 ”](#204) Action 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.