Certificate

A Certificate represents a document proving that a resource (person, equipment, work environment, substance, role, work group, office, PPE, or supplier) has fulfilled a compliance requirement.

Certificates are the proof of compliance: each certificate documents that a resource has completed a requirement (training course, medical examination, maintenance, etc.).

Use this API to:

Find certificates for a person (filter by resource_id with the person_id)
Find certificates by requirement type (filter by action_type)
Create a new certificate to document the completion of a requirement

Creating a certificate does not automatically update the compliance schedule. To update the compliance status, you must create a CertificateAction that links the certificate to the specific action. Without the CertificateAction, the certificate exists but has no effect on the compliance schedule.

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/certificate/index

Returns a paginated list of certificates.

Most useful filters:

resource_id (person_id): all certificates for a person
action_type: certificates by requirement type (e.g. TRAINING for training)
tenant_id (project_id): all certificates in a company

The response includes the name and type of the resource the certificate is issued to, and the project name.

Authorizations

OAuth2
AccessToken

Request Body

Parameters for searching certificates

object

filter

object

certificate_id

Unique identifier of the certificate.

string format: uuid

date_release

Issue date of the certificate.

string format: date

date_expire

Expiration date. May be inherited from the linked action’s validity settings.

string format: date

name

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

Type of requirement this certificate relates to.

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

The ID of the resource this certificate is issued to.

string format: uuid

resource_type

The type of the resource this certificate is issued to.

string

<= 50 characters

Allowed values: PERSON MATERIAL_ITEM ROLE WORK_GROUP WORK_ENVIRONMENT SUBSTANCE EQUIPMENT OFFICE UNIT

resource_name

Display name of the resource this certificate is issued to.

string

<= 255 characters

data

Additional structured data. Content varies by action_type.

object

warning

Whether the certificate has an active warning.

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to.

string format: uuid

subtenant_id

The office associated with this certificate, derived from the linked action.

string format: uuid

subtenant_type

Type of the associated office.

string

<= 50 characters

validity_unit

Unit for the certificate validity period.

string

Allowed values: YEAR MONTH DAY

validity

Number of validity units.

integer

project_name

Name of the project (company).

string

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_expire”).

string

Allowed values: date_release date_expire name action_type

Example

{
  "filter": {
    "resource_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
    "action_type": "TRAINING"
  },
  "per-page": 20,
  "page": 1,
  "sort": "-date_expire"
}

Responses

200

List of certificates

Array<object>

object

certificate_id

Unique identifier of the certificate.

string format: uuid

date_release

Issue date of the certificate.

string format: date

date_expire

Expiration date. May be inherited from the linked action’s validity settings.

string format: date

name

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

Type of requirement this certificate relates to.

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

The ID of the resource this certificate is issued to.

string format: uuid

resource_type

The type of the resource this certificate is issued to.

string

<= 50 characters

Allowed values: PERSON MATERIAL_ITEM ROLE WORK_GROUP WORK_ENVIRONMENT SUBSTANCE EQUIPMENT OFFICE UNIT

resource_name

Display name of the resource this certificate is issued to.

string

<= 255 characters

data

Additional structured data. Content varies by action_type.

object

warning

Whether the certificate has an active warning.

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to.

string format: uuid

subtenant_id

The office associated with this certificate, derived from the linked action.

string format: uuid

subtenant_type

Type of the associated office.

string

<= 50 characters

validity_unit

Unit for the certificate validity period.

string

Allowed values: YEAR MONTH DAY

validity

Number of validity units.

integer

project_name

Name of the project (company).

string

Example

[
  {
    "certificate_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
    "date_release": "2024-01-15",
    "date_expire": "2029-01-15",
    "name": "Fire Safety Training Certificate",
    "action_type": "TRAINING",
    "resource_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
    "resource_type": "PERSON",
    "resource_name": "Smith John",
    "warning": 0,
    "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
    "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "validity_unit": "YEAR",
    "validity": 5,
    "project_name": "Acme Construction Ltd"
  }
]

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

GET

/v2/certificate/view/{id}

Retrieves a single certificate by its ID.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The certificate_id to retrieve.

Responses

200

Certificate found

object

certificate_id

Unique identifier of the certificate.

string format: uuid

date_release

Issue date of the certificate.

string format: date

date_expire

Expiration date. May be inherited from the linked action’s validity settings.

string format: date

name

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

Type of requirement this certificate relates to.

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

The ID of the resource this certificate is issued to.

string format: uuid

resource_type

The type of the resource this certificate is issued to.

string

<= 50 characters

Allowed values: PERSON MATERIAL_ITEM ROLE WORK_GROUP WORK_ENVIRONMENT SUBSTANCE EQUIPMENT OFFICE UNIT

resource_name

Display name of the resource this certificate is issued to.

string

<= 255 characters

data

Additional structured data. Content varies by action_type.

object

warning

Whether the certificate has an active warning.

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to.

string format: uuid

subtenant_id

The office associated with this certificate, derived from the linked action.

string format: uuid

subtenant_type

Type of the associated office.

string

<= 50 characters

validity_unit

Unit for the certificate validity period.

string

Allowed values: YEAR MONTH DAY

validity

Number of validity units.

integer

project_name

Name of the project (company).

string

Example

{
  "certificate_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "date_release": "2024-01-15",
  "date_expire": "2029-01-15",
  "name": "Fire Safety Training Certificate",
  "action_type": "TRAINING",
  "resource_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
  "resource_type": "PERSON",
  "resource_name": "Smith John",
  "warning": 0,
  "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "subtenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "validity_unit": "YEAR",
  "validity": 5,
  "project_name": "Acme Construction Ltd"
}

404

Certificate not found

create

POST

/v2/certificate/create

Creates a new certificate.

Requires date_release, name, action_type, resource_id, and tenant_id (project_id). The certificate_id is auto-generated if not provided.

The resource_id is the ID of the resource the certificate is issued to. What to pass depends on the action_type:

For TRAINING, HEALTH, PER: pass the person_id
For MAINTENANCE: pass the office_equipment_id, office_work_environment_id, or other resource ID
For CHECK: any resource type

After creating the certificate, create a CertificateAction to link it to the specific action. Without this link, the certificate exists but has no effect on the compliance schedule.

To attach a file (e.g. the PDF of the certificate), upload the file via the Attachment API and then create an EntityAttachment to link it to the certificate.

Authorizations

OAuth2
AccessToken

Request Body^required

Certificate object to be created

object

certificate_id

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

string format: uuid

date_release

required

Issue date of the certificate.

string format: date

date_expire

Expiration date of the certificate. If not specified, the certificate does not expire. When linked to an action via CertificateAction, the expiration can be inherited from the action’s validity settings.

string format: date

name

required

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

required

The type of requirement this certificate relates to:

TRAINING: training course
HEALTH: medical surveillance
PER: personal protective equipment
CHECK: check procedure
MAINTENANCE: maintenance

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

required

The ID of the resource this certificate is issued to. What to pass depends on the action_type:

For TRAINING, HEALTH, PER: pass the person_id
For EQUIPMENT: pass the office_equipment_id
For WORK_ENVIRONMENT: pass the office_work_environment_id
For SUBSTANCE: pass the office_substance_id
For ROLE: pass the office_role_id
For WORK_GROUP: pass the work_group_id
For OFFICE: pass the office_id
For PPE: pass the material_item_id
For UNIT: pass the unit_id (supplier) If unknown, search via the corresponding API (e.g. Person index for people).

string format: uuid

data

Additional structured data in JSON format. The content varies depending on the action_type of the certificate (e.g. medical examination results for HEALTH, course details for TRAINING, etc.).

object

warning

1: the certificate has an active warning
0: no warning

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to. Pass the project_id obtained from the Project API.

string format: uuid

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 the certificate validity period.

integer

Example

{
  "date_release": "2024-01-15",
  "date_expire": "2029-01-15",
  "name": "Fire Safety Training Certificate",
  "action_type": "TRAINING",
  "resource_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
  "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "validity_unit": "YEAR",
  "validity": 5
}

Responses

201

Certificate created successfully

object

certificate_id

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

string format: uuid

date_release

required

Issue date of the certificate.

string format: date

date_expire

string format: date

name

required

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

required

The type of requirement this certificate relates to:

TRAINING: training course
HEALTH: medical surveillance
PER: personal protective equipment
CHECK: check procedure
MAINTENANCE: maintenance

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

required

The ID of the resource this certificate is issued to. What to pass depends on the action_type:

For TRAINING, HEALTH, PER: pass the person_id
For EQUIPMENT: pass the office_equipment_id
For WORK_ENVIRONMENT: pass the office_work_environment_id
For SUBSTANCE: pass the office_substance_id
For ROLE: pass the office_role_id
For WORK_GROUP: pass the work_group_id
For OFFICE: pass the office_id
For PPE: pass the material_item_id
For UNIT: pass the unit_id (supplier) If unknown, search via the corresponding API (e.g. Person index for people).

string format: uuid

data

Additional structured data in JSON format. The content varies depending on the action_type of the certificate (e.g. medical examination results for HEALTH, course details for TRAINING, etc.).

object

warning

1: the certificate has an active warning
0: no warning

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to. Pass the project_id obtained from the Project API.

string format: uuid

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 the certificate validity period.

integer

Example

{
  "certificate_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "date_release": "2024-01-15",
  "date_expire": "2029-01-15",
  "name": "Fire Safety Training Certificate",
  "action_type": "TRAINING",
  "resource_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
  "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "validity_unit": "YEAR",
  "validity": 5
}

update

PUT

/v2/certificate/update/{id}

Updates an existing certificate.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The certificate_id to update.

Request Body^required

Certificate fields to update

object

certificate_id

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

string format: uuid

date_release

required

Issue date of the certificate.

string format: date

date_expire

string format: date

name

required

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

required

The type of requirement this certificate relates to:

TRAINING: training course
HEALTH: medical surveillance
PER: personal protective equipment
CHECK: check procedure
MAINTENANCE: maintenance

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

required

The ID of the resource this certificate is issued to. What to pass depends on the action_type:

For TRAINING, HEALTH, PER: pass the person_id
For EQUIPMENT: pass the office_equipment_id
For WORK_ENVIRONMENT: pass the office_work_environment_id
For SUBSTANCE: pass the office_substance_id
For ROLE: pass the office_role_id
For WORK_GROUP: pass the work_group_id
For OFFICE: pass the office_id
For PPE: pass the material_item_id
For UNIT: pass the unit_id (supplier) If unknown, search via the corresponding API (e.g. Person index for people).

string format: uuid

data

Additional structured data in JSON format. The content varies depending on the action_type of the certificate (e.g. medical examination results for HEALTH, course details for TRAINING, etc.).

object

warning

1: the certificate has an active warning
0: no warning

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to. Pass the project_id obtained from the Project API.

string format: uuid

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 the certificate validity period.

integer

Example

{
  "name": "Fire Safety Training Certificate - Renewed",
  "date_expire": "2030-01-15"
}

Responses

200

Certificate updated successfully

object

certificate_id

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

string format: uuid

date_release

required

Issue date of the certificate.

string format: date

date_expire

string format: date

name

required

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

required

The type of requirement this certificate relates to:

TRAINING: training course
HEALTH: medical surveillance
PER: personal protective equipment
CHECK: check procedure
MAINTENANCE: maintenance

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

required

The ID of the resource this certificate is issued to. What to pass depends on the action_type:

For TRAINING, HEALTH, PER: pass the person_id
For EQUIPMENT: pass the office_equipment_id
For WORK_ENVIRONMENT: pass the office_work_environment_id
For SUBSTANCE: pass the office_substance_id
For ROLE: pass the office_role_id
For WORK_GROUP: pass the work_group_id
For OFFICE: pass the office_id
For PPE: pass the material_item_id
For UNIT: pass the unit_id (supplier) If unknown, search via the corresponding API (e.g. Person index for people).

string format: uuid

data

Additional structured data in JSON format. The content varies depending on the action_type of the certificate (e.g. medical examination results for HEALTH, course details for TRAINING, etc.).

object

warning

1: the certificate has an active warning
0: no warning

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to. Pass the project_id obtained from the Project API.

string format: uuid

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 the certificate validity period.

integer

Example

{
  "certificate_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "name": "Fire Safety Training Certificate - Renewed",
  "date_expire": "2030-01-15"
}

404

Certificate not found

delete

DELETE

/v2/certificate/delete/{id}

Deletes a certificate.

If force=false (default), the response lists child entities (CertificateAction links, EntityAttachment links). If force=true, the certificate and all related entities are deleted.

Authorizations

OAuth2
AccessToken

Path Parameters

required

string format: uuid

The certificate_id to delete.

Query Parameters

force

boolean

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

Responses

204

Certificate deleted successfully

400

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

Webhooks

CERTIFICATE::CREATE

POST

Triggered when a new certificate is created.

Request Body

The newly created certificate

object

certificate_id

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

string format: uuid

date_release

required

Issue date of the certificate.

string format: date

date_expire

string format: date

name

required

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

required

The type of requirement this certificate relates to:

TRAINING: training course
HEALTH: medical surveillance
PER: personal protective equipment
CHECK: check procedure
MAINTENANCE: maintenance

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

required

The ID of the resource this certificate is issued to. What to pass depends on the action_type:

For TRAINING, HEALTH, PER: pass the person_id
For EQUIPMENT: pass the office_equipment_id
For WORK_ENVIRONMENT: pass the office_work_environment_id
For SUBSTANCE: pass the office_substance_id
For ROLE: pass the office_role_id
For WORK_GROUP: pass the work_group_id
For OFFICE: pass the office_id
For PPE: pass the material_item_id
For UNIT: pass the unit_id (supplier) If unknown, search via the corresponding API (e.g. Person index for people).

string format: uuid

data

Additional structured data in JSON format. The content varies depending on the action_type of the certificate (e.g. medical examination results for HEALTH, course details for TRAINING, etc.).

object

warning

1: the certificate has an active warning
0: no warning

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to. Pass the project_id obtained from the Project API.

string format: uuid

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 the certificate validity period.

integer

Example

{
  "certificate_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "date_release": "2024-01-15",
  "date_expire": "2029-01-15",
  "name": "Fire Safety Training Certificate",
  "action_type": "TRAINING",
  "resource_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
  "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01",
  "validity_unit": "YEAR",
  "validity": 5
}

Responses

200

Acknowledgment of the webhook event

CERTIFICATE::UPDATE

POST

Triggered when a certificate is updated. Provides the certificate ID and old/new values for each updated field.

Request Body

Updated certificate with old and new values for changed fields

object

entity_id

required

The certificate_id of the updated certificate.

string format: uuid

updated_fields

required

Each key is an updated field name, with its old and new values.

object

key

additional properties

object

old

new

Example

{
  "entity_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "updated_fields": {
    "date_expire": {
      "old": "2029-01-15",
      "new": "2030-01-15"
    }
  }
}

Responses

200

Acknowledgment of the webhook event

CERTIFICATE::DELETE

POST

Triggered when a certificate is deleted.

Request Body

The deleted certificate

object

certificate_id

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

string format: uuid

date_release

required

Issue date of the certificate.

string format: date

date_expire

string format: date

name

required

Descriptive name of the certificate.

string

<= 255 characters

note

Free-text notes.

string

action_type

required

The type of requirement this certificate relates to:

TRAINING: training course
HEALTH: medical surveillance
PER: personal protective equipment
CHECK: check procedure
MAINTENANCE: maintenance

string

Allowed values: TRAINING MAINTENANCE HEALTH CHECK PER

resource_id

required

The ID of the resource this certificate is issued to. What to pass depends on the action_type:

For TRAINING, HEALTH, PER: pass the person_id
For EQUIPMENT: pass the office_equipment_id
For WORK_ENVIRONMENT: pass the office_work_environment_id
For SUBSTANCE: pass the office_substance_id
For ROLE: pass the office_role_id
For WORK_GROUP: pass the work_group_id
For OFFICE: pass the office_id
For PPE: pass the material_item_id
For UNIT: pass the unit_id (supplier) If unknown, search via the corresponding API (e.g. Person index for people).

string format: uuid

data

Additional structured data in JSON format. The content varies depending on the action_type of the certificate (e.g. medical examination results for HEALTH, course details for TRAINING, etc.).

object

warning

1: the certificate has an active warning
0: no warning

integer

Allowed values: 0 1

tenant_id

The project (company) this certificate belongs to. Pass the project_id obtained from the Project API.

string format: uuid

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 the certificate validity period.

integer

Example

{
  "certificate_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c",
  "name": "Fire Safety Training Certificate",
  "action_type": "TRAINING",
  "resource_id": "e3a1f5d2-8c4b-4e7a-9f6d-2b1c3d4e5f6a",
  "tenant_id": "b5a7d602-3fc9-4e2a-9d1a-6e5b4c8f7a01"
}

Responses

200

Acknowledgment of the webhook event

Certificate

Authentication

OAuth2

AccessToken

Operations

index

Authorizations

Request Body

Example

Responses

200

Example

Headers

view

Authorizations

Path Parameters

Responses

200

Example

404

create

Authorizations

Request Body required

Example

Responses

201

Example

update

Authorizations

Path Parameters

Request Body required

Example

Responses

200

Example

404

delete

Authorizations

Path Parameters

Query Parameters

Responses

204

400

Webhooks

CERTIFICATE::CREATE

Request Body

Example

Responses

200

CERTIFICATE::UPDATE

Request Body

Example

Responses

200

CERTIFICATE::DELETE

Request Body

Example

Responses

200

Request Body^required

Request Body^required