--- title: "ActionSession" url: "https://dev.4hse.com/api/actionsession" --- # ActionSession An **ActionSession** represents a scheduled occurrence of a preventive action. The business meaning changes depending on the action type: - For `TRAINING`: a course **edition** - For `HEALTH`: a medical **visit** - For `PER`: a PPE **delivery** - For `MAINTENANCE`: a maintenance **order** - For `CHECK`: a check **session** or inspection report A session belongs to an action and can have: - One or more **dates** (ActionSessionDate): the days when it takes place - One or more **subscriptions** (ActionSessionSubscription): the resources enrolled in this specific occurrence Use this API to: - Schedule a course edition, maintenance order, medical visit, or PPE delivery - Find sessions for an action (filter by `action_id`) - Check enrollment counts and their status (completed, failed, pending) A session can have its own `validity` and `validity_unit` values, which override the action’s values for certificates generated from this specific occurrence. 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-indexActionSession-post) POST /v2/action-session/index - Returns a paginated list of action sessions. Most useful filters: - `action_id`: all sessions for a specific action - `action_type` + `subtenant_id`: all sessions of a type in an office - `tenant_id`: all sessions in a company The response includes enrollment counts and session dates. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/actionsession/#oauth2)** - **[AccessToken](/api/actionsession/#accesstoken)** #### Request Body [Section titled “Request Body ”](#request-body) Parameters for searching action sessions Select media typeapplication/json object **filter** object **action\_session\_id** Unique identifier of the session. string format: uuid **action\_id** The action this session belongs to. string format: uuid **validity\_unit** Validity unit specific to this session. string Allowed values: YEAR MONTH DAY **validity** Number of validity units specific to this session. integer **data** One of: - [object](#tab-panel-0) - [object](#tab-panel-1) - [object](#tab-panel-2) - [object](#tab-panel-3) - [object](#tab-panel-4) Data fields for TRAINING sessions (course editions). object **type** Type of course edition: `base` = initial course, `update` = refresher/update course. string Allowed values: base update **teacher** Name of the instructor/teacher. string **supplier** Name of the training provider/supplier. string **location** Location where the course takes place. string Data fields for HEALTH sessions (medical visits). object **type** Type of medical visit: - `PERIODIC`: periodic surveillance visit - `PREVENTIVE`: pre-employment/preventive visit - `REQUEST`: visit requested by the worker - `JOBCHANGE`: visit due to change of job role - `END`: end-of-employment visit - `SICK`: visit after sick leave string Allowed values: PERIODIC PREVENTIVE REQUEST JOBCHANGE END SICK **location** Name or address of the medical facility. string Data fields for MAINTENANCE sessions (maintenance orders). object **name** Name or code of the maintenance order. string **description** Detailed description of the maintenance work (may contain HTML). string **location** Location where the maintenance takes place. string Data fields for CHECK sessions (inspection reports). object **location** Location where the check/inspection takes place. string Data fields for PER sessions (PPE deliveries). object **location** Location where the PPE delivery takes place. string **subtenant\_id** The office of this session. string format: uuid **tenant\_id** The project of this session. string format: uuid **action\_code** Code of the linked action. string **action\_name** Name of the linked action. string **action\_type** Type of the linked action. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **count\_subscribed** Total number of resources enrolled in this session. integer **count\_done** Number of enrolled resources that completed the session successfully. integer **count\_fail** Number of enrolled resources that did not pass. integer **count\_unknown** Number of enrolled resources whose outcome has not been recorded yet. integer **date\_begin** Start date of the session (from the earliest ActionSessionDate). string format: date **date\_end** End date of the session (from the latest ActionSessionDate). string format: date **manager** Session managers (JSON). string format: json **assignee** Session assignees (JSON). string format: json **watcher** Session watchers (JSON). string format: json **per-page** integer default: 100 \>= 1 **page** integer default: 1 \>= 1 **sort** Field to sort by. Prefix with minus for descending order (e.g. “-date\_begin”). string Allowed values: action\_code action\_name action\_type date\_begin date\_end ##### Example ``` { "filter": { "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "action_type": "TRAINING" }, "per-page": 10, "page": 1, "sort": "-date_begin"} ``` #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) List of action sessions Select media typeapplication/json Array object **action\_session\_id** Unique identifier of the session. string format: uuid **action\_id** The action this session belongs to. string format: uuid **validity\_unit** Validity unit specific to this session. string Allowed values: YEAR MONTH DAY **validity** Number of validity units specific to this session. integer **data** One of: - [object](#tab-panel-5) - [object](#tab-panel-6) - [object](#tab-panel-7) - [object](#tab-panel-8) - [object](#tab-panel-9) Data fields for TRAINING sessions (course editions). object **type** Type of course edition: `base` = initial course, `update` = refresher/update course. string Allowed values: base update **teacher** Name of the instructor/teacher. string **supplier** Name of the training provider/supplier. string **location** Location where the course takes place. string Data fields for HEALTH sessions (medical visits). object **type** Type of medical visit: - `PERIODIC`: periodic surveillance visit - `PREVENTIVE`: pre-employment/preventive visit - `REQUEST`: visit requested by the worker - `JOBCHANGE`: visit due to change of job role - `END`: end-of-employment visit - `SICK`: visit after sick leave string Allowed values: PERIODIC PREVENTIVE REQUEST JOBCHANGE END SICK **location** Name or address of the medical facility. string Data fields for MAINTENANCE sessions (maintenance orders). object **name** Name or code of the maintenance order. string **description** Detailed description of the maintenance work (may contain HTML). string **location** Location where the maintenance takes place. string Data fields for CHECK sessions (inspection reports). object **location** Location where the check/inspection takes place. string Data fields for PER sessions (PPE deliveries). object **location** Location where the PPE delivery takes place. string **subtenant\_id** The office of this session. string format: uuid **tenant\_id** The project of this session. string format: uuid **action\_code** Code of the linked action. string **action\_name** Name of the linked action. string **action\_type** Type of the linked action. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **count\_subscribed** Total number of resources enrolled in this session. integer **count\_done** Number of enrolled resources that completed the session successfully. integer **count\_fail** Number of enrolled resources that did not pass. integer **count\_unknown** Number of enrolled resources whose outcome has not been recorded yet. integer **date\_begin** Start date of the session (from the earliest ActionSessionDate). string format: date **date\_end** End date of the session (from the latest ActionSessionDate). string format: date **manager** Session managers (JSON). string format: json **assignee** Session assignees (JSON). string format: json **watcher** Session watchers (JSON). string format: json ##### Example ``` [ { "action_session_id": "b1c2d3e4-f5a6-7890-bcde-f12345678901", "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "validity_unit": "YEAR", "validity": 5, "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01", "action_code": "FST-01", "action_name": "Fire Safety Training Medium Risk", "action_type": "TRAINING", "count_subscribed": 12, "count_done": 10, "count_fail": 1, "count_unknown": 1, "date_begin": "2024-03-15", "date_end": "2024-03-16" }] ``` #### 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-createActionSession-post) POST /v2/action-session/create - Creates a new session for an action. Requires `action_id`, `subtenant_id` (office\_id), and `tenant_id` (project\_id). The `action_session_id` is auto-generated if not provided. Creating a session does **not** automatically create dates or enrollments. After creation, create ActionSessionDate entries (session dates) and ActionSessionSubscription entries (enrollments) separately. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/actionsession/#oauth2)** - **[AccessToken](/api/actionsession/#accesstoken)** #### Request Body required [Section titled “Request Body required ”](#request-body) Action session to create Select media typeapplication/json object **action\_session\_id** Unique identifier of the session. Auto-generated if not provided on creation. string format: uuid **action\_id** required The action this session belongs to. Pass the `action_id` obtained from the Action API. string format: uuid **validity\_unit** Validity unit specific to this session. If set, overrides the action’s validity for certificates generated from this occurrence. string Allowed values: YEAR MONTH DAY **validity** Number of validity units specific to this session. integer **manager** Session managers (JSON). string format: json **assignee** Session assignees (JSON). string format: json **watcher** Session watchers (JSON). string format: json **data** One of: - [object](#tab-panel-10) - [object](#tab-panel-11) - [object](#tab-panel-12) - [object](#tab-panel-13) - [object](#tab-panel-14) Data fields for TRAINING sessions (course editions). object **type** Type of course edition: `base` = initial course, `update` = refresher/update course. string Allowed values: base update **teacher** Name of the instructor/teacher. string **supplier** Name of the training provider/supplier. string **location** Location where the course takes place. string Data fields for HEALTH sessions (medical visits). object **type** Type of medical visit: - `PERIODIC`: periodic surveillance visit - `PREVENTIVE`: pre-employment/preventive visit - `REQUEST`: visit requested by the worker - `JOBCHANGE`: visit due to change of job role - `END`: end-of-employment visit - `SICK`: visit after sick leave string Allowed values: PERIODIC PREVENTIVE REQUEST JOBCHANGE END SICK **location** Name or address of the medical facility. string Data fields for MAINTENANCE sessions (maintenance orders). object **name** Name or code of the maintenance order. string **description** Detailed description of the maintenance work (may contain HTML). string **location** Location where the maintenance takes place. string Data fields for CHECK sessions (inspection reports). object **location** Location where the check/inspection takes place. string Data fields for PER sessions (PPE deliveries). object **location** Location where the PPE delivery takes place. string **subtenant\_id** required The office (work location) of this session. Pass the `office_id`. string format: uuid **tenant\_id** required The project (company) of this session. Pass the `project_id`. string format: uuid ##### Example ``` { "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "validity_unit": "YEAR", "validity": 5, "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 session created successfully Select media typeapplication/json object **action\_session\_id** Unique identifier of the session. Auto-generated if not provided on creation. string format: uuid **action\_id** required The action this session belongs to. Pass the `action_id` obtained from the Action API. string format: uuid **validity\_unit** Validity unit specific to this session. If set, overrides the action’s validity for certificates generated from this occurrence. string Allowed values: YEAR MONTH DAY **validity** Number of validity units specific to this session. integer **manager** Session managers (JSON). string format: json **assignee** Session assignees (JSON). string format: json **watcher** Session watchers (JSON). string format: json **data** One of: - [object](#tab-panel-15) - [object](#tab-panel-16) - [object](#tab-panel-17) - [object](#tab-panel-18) - [object](#tab-panel-19) Data fields for TRAINING sessions (course editions). object **type** Type of course edition: `base` = initial course, `update` = refresher/update course. string Allowed values: base update **teacher** Name of the instructor/teacher. string **supplier** Name of the training provider/supplier. string **location** Location where the course takes place. string Data fields for HEALTH sessions (medical visits). object **type** Type of medical visit: - `PERIODIC`: periodic surveillance visit - `PREVENTIVE`: pre-employment/preventive visit - `REQUEST`: visit requested by the worker - `JOBCHANGE`: visit due to change of job role - `END`: end-of-employment visit - `SICK`: visit after sick leave string Allowed values: PERIODIC PREVENTIVE REQUEST JOBCHANGE END SICK **location** Name or address of the medical facility. string Data fields for MAINTENANCE sessions (maintenance orders). object **name** Name or code of the maintenance order. string **description** Detailed description of the maintenance work (may contain HTML). string **location** Location where the maintenance takes place. string Data fields for CHECK sessions (inspection reports). object **location** Location where the check/inspection takes place. string Data fields for PER sessions (PPE deliveries). object **location** Location where the PPE delivery takes place. string **subtenant\_id** required The office (work location) of this session. Pass the `office_id`. string format: uuid **tenant\_id** required The project (company) of this session. Pass the `project_id`. string format: uuid ##### Example ``` { "action_session_id": "b1c2d3e4-f5a6-7890-bcde-f12345678901", "action_id": "c4d5e6f7-a8b9-0c1d-2e3f-4a5b6c7d8e9f", "validity_unit": "YEAR", "validity": 5, "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"} ``` ### view [Section titled “view”](#operation-viewActionSession-get) GET /v2/action-session/view/{id} - Retrieves a single action session by its ID. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/actionsession/#oauth2)** - **[AccessToken](/api/actionsession/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The action\_session\_id to retrieve. #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Action session found Select media typeapplication/json object **action\_session\_id** Unique identifier of the session. string format: uuid **action\_id** The action this session belongs to. string format: uuid **validity\_unit** Validity unit specific to this session. string Allowed values: YEAR MONTH DAY **validity** Number of validity units specific to this session. integer **data** One of: - [object](#tab-panel-20) - [object](#tab-panel-21) - [object](#tab-panel-22) - [object](#tab-panel-23) - [object](#tab-panel-24) Data fields for TRAINING sessions (course editions). object **type** Type of course edition: `base` = initial course, `update` = refresher/update course. string Allowed values: base update **teacher** Name of the instructor/teacher. string **supplier** Name of the training provider/supplier. string **location** Location where the course takes place. string Data fields for HEALTH sessions (medical visits). object **type** Type of medical visit: - `PERIODIC`: periodic surveillance visit - `PREVENTIVE`: pre-employment/preventive visit - `REQUEST`: visit requested by the worker - `JOBCHANGE`: visit due to change of job role - `END`: end-of-employment visit - `SICK`: visit after sick leave string Allowed values: PERIODIC PREVENTIVE REQUEST JOBCHANGE END SICK **location** Name or address of the medical facility. string Data fields for MAINTENANCE sessions (maintenance orders). object **name** Name or code of the maintenance order. string **description** Detailed description of the maintenance work (may contain HTML). string **location** Location where the maintenance takes place. string Data fields for CHECK sessions (inspection reports). object **location** Location where the check/inspection takes place. string Data fields for PER sessions (PPE deliveries). object **location** Location where the PPE delivery takes place. string **subtenant\_id** The office of this session. string format: uuid **tenant\_id** The project of this session. string format: uuid **action\_code** Code of the linked action. string **action\_name** Name of the linked action. string **action\_type** Type of the linked action. string Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER **count\_subscribed** Total number of resources enrolled in this session. integer **count\_done** Number of enrolled resources that completed the session successfully. integer **count\_fail** Number of enrolled resources that did not pass. integer **count\_unknown** Number of enrolled resources whose outcome has not been recorded yet. integer **date\_begin** Start date of the session (from the earliest ActionSessionDate). string format: date **date\_end** End date of the session (from the latest ActionSessionDate). string format: date **manager** Session managers (JSON). string format: json **assignee** Session assignees (JSON). string format: json **watcher** Session watchers (JSON). string format: json ##### 404 [Section titled “404 ”](#404) Action session not found ### update [Section titled “update”](#operation-updateActionSession-put) PUT /v2/action-session/update/{id} - Updates an existing action session. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/actionsession/#oauth2)** - **[AccessToken](/api/actionsession/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The action\_session\_id to update. #### Request Body required [Section titled “Request Body required ”](#request-body) Fields to update Select media typeapplication/json object **action\_session\_id** Unique identifier of the session. Auto-generated if not provided on creation. string format: uuid **action\_id** required The action this session belongs to. Pass the `action_id` obtained from the Action API. string format: uuid **validity\_unit** Validity unit specific to this session. If set, overrides the action’s validity for certificates generated from this occurrence. string Allowed values: YEAR MONTH DAY **validity** Number of validity units specific to this session. integer **manager** Session managers (JSON). string format: json **assignee** Session assignees (JSON). string format: json **watcher** Session watchers (JSON). string format: json **data** One of: - [object](#tab-panel-25) - [object](#tab-panel-26) - [object](#tab-panel-27) - [object](#tab-panel-28) - [object](#tab-panel-29) Data fields for TRAINING sessions (course editions). object **type** Type of course edition: `base` = initial course, `update` = refresher/update course. string Allowed values: base update **teacher** Name of the instructor/teacher. string **supplier** Name of the training provider/supplier. string **location** Location where the course takes place. string Data fields for HEALTH sessions (medical visits). object **type** Type of medical visit: - `PERIODIC`: periodic surveillance visit - `PREVENTIVE`: pre-employment/preventive visit - `REQUEST`: visit requested by the worker - `JOBCHANGE`: visit due to change of job role - `END`: end-of-employment visit - `SICK`: visit after sick leave string Allowed values: PERIODIC PREVENTIVE REQUEST JOBCHANGE END SICK **location** Name or address of the medical facility. string Data fields for MAINTENANCE sessions (maintenance orders). object **name** Name or code of the maintenance order. string **description** Detailed description of the maintenance work (may contain HTML). string **location** Location where the maintenance takes place. string Data fields for CHECK sessions (inspection reports). object **location** Location where the check/inspection takes place. string Data fields for PER sessions (PPE deliveries). object **location** Location where the PPE delivery takes place. string **subtenant\_id** required The office (work location) of this session. Pass the `office_id`. string format: uuid **tenant\_id** required The project (company) of this session. Pass the `project_id`. string format: uuid ##### Example ``` { "validity_unit": "YEAR", "validity": 3} ``` #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Action session updated successfully Select media typeapplication/json object **action\_session\_id** Unique identifier of the session. Auto-generated if not provided on creation. string format: uuid **action\_id** required The action this session belongs to. Pass the `action_id` obtained from the Action API. string format: uuid **validity\_unit** Validity unit specific to this session. If set, overrides the action’s validity for certificates generated from this occurrence. string Allowed values: YEAR MONTH DAY **validity** Number of validity units specific to this session. integer **manager** Session managers (JSON). string format: json **assignee** Session assignees (JSON). string format: json **watcher** Session watchers (JSON). string format: json **data** One of: - [object](#tab-panel-30) - [object](#tab-panel-31) - [object](#tab-panel-32) - [object](#tab-panel-33) - [object](#tab-panel-34) Data fields for TRAINING sessions (course editions). object **type** Type of course edition: `base` = initial course, `update` = refresher/update course. string Allowed values: base update **teacher** Name of the instructor/teacher. string **supplier** Name of the training provider/supplier. string **location** Location where the course takes place. string Data fields for HEALTH sessions (medical visits). object **type** Type of medical visit: - `PERIODIC`: periodic surveillance visit - `PREVENTIVE`: pre-employment/preventive visit - `REQUEST`: visit requested by the worker - `JOBCHANGE`: visit due to change of job role - `END`: end-of-employment visit - `SICK`: visit after sick leave string Allowed values: PERIODIC PREVENTIVE REQUEST JOBCHANGE END SICK **location** Name or address of the medical facility. string Data fields for MAINTENANCE sessions (maintenance orders). object **name** Name or code of the maintenance order. string **description** Detailed description of the maintenance work (may contain HTML). string **location** Location where the maintenance takes place. string Data fields for CHECK sessions (inspection reports). object **location** Location where the check/inspection takes place. string Data fields for PER sessions (PPE deliveries). object **location** Location where the PPE delivery takes place. string **subtenant\_id** required The office (work location) of this session. Pass the `office_id`. string format: uuid **tenant\_id** required The project (company) of this session. Pass the `project_id`. string format: uuid ##### 404 [Section titled “404 ”](#404) Action session not found ### delete [Section titled “delete”](#operation-deleteActionSession-delete) DELETE /v2/action-session/delete/{id} - Deletes an action session. If `force=false` (default), the response lists child entities (dates, enrollments). If `force=true`, the session and all related entities are deleted. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/actionsession/#oauth2)** - **[AccessToken](/api/actionsession/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The action\_session\_id to delete. #### Query Parameters [Section titled “Query Parameters ”](#query-parameters) **force** boolean If true, deletes the session and all child entities. If false, returns a preview of affected entities. #### Responses [Section titled “ Responses ”](#responses) ##### 204 [Section titled “204 ”](#204) Action session 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.