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

OAuth2

Security scheme type: oauth2

Flow type: password

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

AccessToken

Security scheme type: apiKey

Query parameter name: access-token

Operations

index

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

OAuth2
AccessToken

Request Body

Parameters for searching action sessions

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:

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

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

200

List of action sessions

Array<object>

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:

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

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

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

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

OAuth2
AccessToken

Request Body^required

Action session to create

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:

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

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

201

Action session created successfully

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:

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

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

GET

/v2/action-session/view/{id}

Retrieves a single action session by its ID.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The action_session_id to retrieve.

Responses

200

Action session found

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:

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

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

Action session not found

update

PUT

/v2/action-session/update/{id}

Updates an existing action session.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The action_session_id to update.

Request Body^required

Fields to update

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:

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

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

200

Action session updated successfully

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:

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

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

Action session not found

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

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The action_session_id to delete.

Query Parameters

force

boolean

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

ActionSession

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Request Body

Example

Responses

200

Example

Headers

create

Authorizations

Request Body required

Example

Responses

201

Example

view

Authorizations

Path Parameters

Responses

200

404

update

Authorizations

Path Parameters

Request Body required

Example

Responses

200

404

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

Request Body^required

Request Body^required