--- title: "Certificate" url: "https://dev.4hse.com/api/certificate" --- # 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 [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-indexCertificate-post) 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 [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/certificate/#oauth2)** - **[AccessToken](/api/certificate/#accesstoken)** #### Request Body [Section titled “Request Body ”](#request-body) Parameters for searching certificates Select media typeapplication/json 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 **status** Lifecycle status of the certificate (draft, valid, revoked, rejected). Can be used as a filter. string Allowed values: draft valid revoked rejected **time\_precision** Whether `date_release`/`date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision (`1`) or only the date is used (`0`). integer Allowed values: 0 1 **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 [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) List of certificates Select media typeapplication/json Array 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 **status** Lifecycle status of the certificate (draft, valid, revoked, rejected). Can be used as a filter. string Allowed values: draft valid revoked rejected **time\_precision** Whether `date_release`/`date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision (`1`) or only the date is used (`0`). integer Allowed values: 0 1 **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 [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 ### view [Section titled “view”](#operation-viewCertificate-get) GET /v2/certificate/view/{id} - Retrieves a single certificate by its ID. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/certificate/#oauth2)** - **[AccessToken](/api/certificate/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The certificate\_id to retrieve. #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Certificate found Select media typeapplication/json 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 **status** Lifecycle status of the certificate (draft, valid, revoked, rejected). Can be used as a filter. string Allowed values: draft valid revoked rejected **time\_precision** Whether `date_release`/`date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision (`1`) or only the date is used (`0`). integer Allowed values: 0 1 **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 [Section titled “404 ”](#404) Certificate not found ### verify [Section titled “verify”](#operation-verifyCertificate-get) GET /v2/certificate/verify - Returns a single certificate (same payload as `view`) plus `attachment_urls`: pre-signed URLs for every certificate attachment, so the public (unauthenticated) verification page can display/download them. Accessible both by authenticated clients and via UrlSign: pass the `urlsign` query parameter authorizing access (handled by AclFilter). The pre-signed attachment URLs reuse the remaining TTL of that token; for authenticated calls a default TTL is used. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/certificate/#oauth2)** - **[AccessToken](/api/certificate/#accesstoken)** #### Query Parameters [Section titled “Query Parameters ”](#query-parameters) **id** required string format: uuid The certificate\_id to verify. **urlsign** string UrlSign token authorizing public access. Optional for authenticated clients. #### Responses [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Certificate found Select media typeapplication/json Certificate payload (as `view`) plus pre-signed attachment URLs. 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 **status** Lifecycle status of the certificate (draft, valid, revoked, rejected). Can be used as a filter. string Allowed values: draft valid revoked rejected **time\_precision** Whether `date_release`/`date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision (`1`) or only the date is used (`0`). integer Allowed values: 0 1 **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 **attachment\_urls** Pre-signed URLs for the certificate attachments. Array object **url** Pre-signed URL (`/v2/attachment/verify/...?urlsign=...`) to display/download the attachment. string **name** File name of the attachment. string **mime\_type** MIME type of the attachment, when known. string nullable **purpose** Purpose/role of the attachment, when set. string nullable ##### 404 [Section titled “404 ”](#404) Certificate not found ### create [Section titled “create”](#operation-createCertificate-post) 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 [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/certificate/#oauth2)** - **[AccessToken](/api/certificate/#accesstoken)** #### Request Body required [Section titled “Request Body required ”](#request-body) Certificate object to be created Select media typeapplication/json 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 **status** Lifecycle status of the certificate: - `draft`: not yet finalized; does not affect the compliance schedule - `valid`: active and effective - `revoked`: revoked after issuance - `rejected`: not approved string default: valid Allowed values: draft valid revoked rejected **time\_precision** - `1`: `date_release` and `date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision - `0` (default): only the date is used integer 0 Allowed values: 0 1 **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 [Section titled “ Responses ”](#responses) ##### 201 [Section titled “201 ”](#201) Certificate created successfully Select media typeapplication/json 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 **status** Lifecycle status of the certificate: - `draft`: not yet finalized; does not affect the compliance schedule - `valid`: active and effective - `revoked`: revoked after issuance - `rejected`: not approved string default: valid Allowed values: draft valid revoked rejected **time\_precision** - `1`: `date_release` and `date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision - `0` (default): only the date is used integer 0 Allowed values: 0 1 **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 [Section titled “update”](#operation-updateCertificate-put) PUT /v2/certificate/update/{id} - Updates an existing certificate. ## Authorizations [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/certificate/#oauth2)** - **[AccessToken](/api/certificate/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The certificate\_id to update. #### Request Body required [Section titled “Request Body required ”](#request-body) Certificate fields to update Select media typeapplication/json 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 **status** Lifecycle status of the certificate: - `draft`: not yet finalized; does not affect the compliance schedule - `valid`: active and effective - `revoked`: revoked after issuance - `rejected`: not approved string default: valid Allowed values: draft valid revoked rejected **time\_precision** - `1`: `date_release` and `date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision - `0` (default): only the date is used integer 0 Allowed values: 0 1 **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 [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Certificate updated successfully Select media typeapplication/json 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 **status** Lifecycle status of the certificate: - `draft`: not yet finalized; does not affect the compliance schedule - `valid`: active and effective - `revoked`: revoked after issuance - `rejected`: not approved string default: valid Allowed values: draft valid revoked rejected **time\_precision** - `1`: `date_release` and `date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision - `0` (default): only the date is used integer 0 Allowed values: 0 1 **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 [Section titled “404 ”](#404) Certificate not found ### delete [Section titled “delete”](#operation-deleteCertificate-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 [Section titled “Authorizations ”](#authorizations) - **[OAuth2](/api/certificate/#oauth2)** - **[AccessToken](/api/certificate/#accesstoken)** #### Path Parameters [Section titled “Path Parameters ”](#path-parameters) **id** required string format: uuid The certificate\_id to delete. #### Query Parameters [Section titled “Query Parameters ”](#query-parameters) **force** boolean If true, deletes the certificate and all child entities. If false, returns a preview of affected entities. #### Responses [Section titled “ Responses ”](#responses) ##### 204 [Section titled “204 ”](#204) Certificate deleted successfully ##### 400 [Section titled “400 ”](#400) Preview of entities that would be deleted (returned when force=false) ## Webhooks [Section titled “Webhooks”](#webhooks) #### CERTIFICATE::CREATE [Section titled “CERTIFICATE::CREATE”](#webhook-CERTIFICATE::CREATE) POST Triggered when a new certificate is created. #### Request Body [Section titled “Request Body ”](#request-body) The newly created certificate Select media typeapplication/json 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 **status** Lifecycle status of the certificate: - `draft`: not yet finalized; does not affect the compliance schedule - `valid`: active and effective - `revoked`: revoked after issuance - `rejected`: not approved string default: valid Allowed values: draft valid revoked rejected **time\_precision** - `1`: `date_release` and `date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision - `0` (default): only the date is used integer 0 Allowed values: 0 1 **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 [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Acknowledgment of the webhook event #### CERTIFICATE::UPDATE [Section titled “CERTIFICATE::UPDATE”](#webhook-CERTIFICATE::UPDATE) POST Triggered when a certificate is updated. Provides the certificate ID and old/new values for each updated field. #### Request Body [Section titled “Request Body ”](#request-body) Updated certificate with old and new values for changed fields Select media typeapplication/json 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 [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Acknowledgment of the webhook event #### CERTIFICATE::DELETE [Section titled “CERTIFICATE::DELETE”](#webhook-CERTIFICATE::DELETE) POST Triggered when a certificate is deleted. #### Request Body [Section titled “Request Body ”](#request-body) The deleted certificate Select media typeapplication/json 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 **status** Lifecycle status of the certificate: - `draft`: not yet finalized; does not affect the compliance schedule - `valid`: active and effective - `revoked`: revoked after issuance - `rejected`: not approved string default: valid Allowed values: draft valid revoked rejected **time\_precision** - `1`: `date_release` and `date_expire` carry a time component (15-minute granularity) and expiration is evaluated with datetime precision - `0` (default): only the date is used integer 0 Allowed values: 0 1 **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 [Section titled “ Responses ”](#responses) ##### 200 [Section titled “200 ”](#200) Acknowledgment of the webhook event 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.