Certification

Get Certifications

This endpoint retrieves a list of all certification of a specific organisation.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

Query Parameters

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response Body

A hash with a data property that contains an array of up to the limit of certifications. Each entry in the array is a separate certification object. If there are no more certifications, the resulting array will be empty.

dataobject

itemsobject[]

iduuid

The certification id

namestring

The name of certification

typeenum<string>

The type of certification

mandatoryboolean

Whether the certification is mandatory

descriptionstring

The description of the certification

supporting_documentationboolean

Whether supporting documentation is required

certification_number_allowedboolean

Whether a certification number is allowed

additional_info_filesstring[]

Additional info files attached to the certification. Empty array if none

use_expiry_dateboolean

Whether the certification uses an expiry date

due_within_daysinteger

Number of days within which the certification is due

approval_requiredboolean

Whether approval is required for the certification

access_restrictedboolean

Whether access to the certification is restricted

confirm_driving_offensesboolean

Whether driving offenses confirmation is required

countystring

🇬🇧 UK

The county. Only included for UK organisations

statestring

🇦🇺 AU

The state. Only included for AU organisations

territorystring

🌍 Global

🇲🇾 MY

🇸🇬 SG

🇳🇿 NZ

🇨🇦 CA

The territory. Only included for organisations outside AU and UK

frequency_attributesobject

Frequency attributes for the certification. Empty object if not set.

assigneesobject

Assignee configuration for the certification

approversobject

Approver configuration for the certification

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

Total pages

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "items": [      {        "id": "6538a2bb-2b34-4437-9a00-92af3dab5b59",        "name": "Full-disk encryption",        "type": "check",        "mandatory": true,        "description": "Employees must complete full-disk encryption setup",        "supporting_documentation": true,        "certification_number_allowed": false,        "additional_info_files": [],        "use_expiry_date": true,        "due_within_days": 30,        "approval_required": true,        "access_restricted": false,        "confirm_driving_offenses": false,        "state": "NSW",        "frequency_attributes": {          "frequency": "renewing",          "repeat": "months",          "timer": 12        },        "assignees": {          "assigned_to_all_employees": true,          "assigned_to_all_contractors": false,          "employee_ids": [],          "work_location_ids": [],          "group_ids": []        },        "approvers": {          "approvable_by_direct_managers": true,          "approvable_by_indirect_managers": false,          "employee_ids": [],          "work_location_ids": [],          "group_ids": []        }      },      {        "id": "3128a2bb-2b34-4437-9a00-92af3dab5b59",        "name": "System Training",        "type": "training",        "mandatory": false,        "description": null,        "supporting_documentation": false,        "certification_number_allowed": true,        "additional_info_files": [],        "use_expiry_date": false,        "due_within_days": null,        "approval_required": false,        "access_restricted": false,        "confirm_driving_offenses": false,        "state": null,        "frequency_attributes": {},        "assignees": {          "assigned_to_all_employees": false,          "assigned_to_all_contractors": false,          "employee_ids": [],          "work_location_ids": [],          "group_ids": []        },        "approvers": {          "approvable_by_direct_managers": false,          "approvable_by_indirect_managers": false,          "employee_ids": [],          "work_location_ids": [],          "group_ids": []        }      },      {        "id": "5562a2bb-2b34-4437-9a00-92af3dab5b59",        "name": "Staff training",        "type": "training",        "mandatory": true,        "description": "Annual staff training requirement",        "supporting_documentation": false,        "certification_number_allowed": false,        "additional_info_files": [],        "use_expiry_date": true,        "due_within_days": 60,        "approval_required": false,        "access_restricted": false,        "confirm_driving_offenses": false,        "territory": "",        "frequency_attributes": {          "frequency": "once",          "repeat": null,          "timer": null        },        "assignees": {          "assigned_to_all_employees": true,          "assigned_to_all_contractors": true,          "employee_ids": [],          "work_location_ids": [],          "group_ids": []        },        "approvers": {          "approvable_by_direct_managers": true,          "approvable_by_indirect_managers": false,          "employee_ids": [],          "work_location_ids": [],          "group_ids": []        }      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 3,    "total_pages": 1  }}

Get Certification

This endpoint retrieves a specific certification.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

certification_iduuidrequired

The certification id

Response Body

dataobject

iduuid

The certification id

namestring

The name of certification

typeenum<string>

The type of certification

mandatoryboolean

Whether the certification is mandatory

descriptionstring

The description of the certification

supporting_documentationboolean

Whether supporting documentation is required

certification_number_allowedboolean

Whether a certification number is allowed

additional_info_filesstring[]

Additional info files attached to the certification. Empty array if none

use_expiry_dateboolean

Whether the certification uses an expiry date

due_within_daysinteger

Number of days within which the certification is due

approval_requiredboolean

Whether approval is required for the certification

access_restrictedboolean

Whether access to the certification is restricted

confirm_driving_offensesboolean

Whether driving offenses confirmation is required

countystring

🇬🇧 UK

The county. Only included for UK organisations

statestring

🇦🇺 AU

The state. Only included for AU organisations

territorystring

🌍 Global

🇲🇾 MY

🇸🇬 SG

🇳🇿 NZ

🇨🇦 CA

The territory. Only included for organisations outside AU and UK

frequency_attributesobject

Frequency attributes for the certification. Empty object if not set.

assigneesobject

Assignee configuration for the certification

approversobject

Approver configuration for the certification

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "id": "6538a2bb-2b34-4437-9a00-92af3dab5b59",    "name": "Full-disk encryption",    "type": "check",    "mandatory": true,    "description": "Employees must complete full-disk encryption setup",    "supporting_documentation": true,    "certification_number_allowed": false,    "additional_info_files": [],    "use_expiry_date": true,    "due_within_days": 30,    "approval_required": true,    "access_restricted": false,    "confirm_driving_offenses": false,    "state": "NSW",    "frequency_attributes": {      "frequency": "renewing",      "repeat": "months",      "timer": 12    },    "assignees": {      "assigned_to_all_employees": true,      "assigned_to_all_contractors": false,      "employee_ids": [],      "work_location_ids": [],      "group_ids": []    },    "approvers": {      "approvable_by_direct_managers": true,      "approvable_by_indirect_managers": false,      "employee_ids": [],      "work_location_ids": [],      "group_ids": []    }  }}

Create Certification

This endpoint creates a new certification within an organisation. The create operation is asynchronous, so a polling key is returned for tracking the operation status using the Polling Status API.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications

Path Parameters

organisation_iduuidrequired

The ID of the organisation

Request Body

namestringrequired

Certification name (max 255 characters)

typeenum<string>required

The category of the certification. Cannot be changed after creation.

descriptionstring

Certification description

stateenum<string>

🇦🇺 AU

The regional state where the certification applies

territorystring

🌍 Global

Territory where certification applies

countystring

🇬🇧 UK

County where certification applies

mandatoryboolean

Whether this certification is mandatory. Cannot be changed after creation. Default: false.

access_restrictedboolean

Whether access is restricted to specific security groups. Cannot be changed after creation. Default: false.

due_within_daysinteger

Days to complete after assignment (min: 1)

supporting_documentationboolean

Whether supporting documentation is required

certification_number_allowedboolean

Whether certification number is allowed

confirm_driving_offensesboolean

Enable the option for the assignee to confirm driving offenses when completing the certification

use_expiry_dateboolean

Whether to use an expiry date for the certification

Note

The frequency_attributes field is disabled if this option is true

frequency_attributesobject

Frequency configuration for recurring certifications

assigneesobject

Configuration for assigning certifications

approval_requiredboolean

Whether approval is required for this certification

Note

The approvers field is disabled if this option is false

approversobject

Configuration for approving certifications

additional_info_filesstring[]

Additional info file URLs

Response Body

Returns a polling key that can be used to track the async create operation status

dataobject

polling_keystring

A unique key used to poll for the status of the certification creation job.

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Working With Children Check",    "type": "check",    "description": "Required for all staff working with children under 18 years of age",    "state": "NSW",    "mandatory": true,    "due_within_days": 30,    "supporting_documentation": true,    "certification_number_allowed": true,    "confirm_driving_offenses": false,    "use_expiry_date": false,    "frequency_attributes": {      "frequency": "renewing",      "repeat": "months",      "timer": 36    },    "assignees": {      "assigned_to_all_organisation_members": false,      "assigned_to_all_organisation_contractors": false,      "employee_ids": [        "assignee-member-uuid-1234"      ],      "contractor_ids": [        "assignee-contractor-uuid-1234"      ],      "group_ids": [        "assignee-group-uuid-1234"      ],      "work_location_ids": [        "assignee-work-location-uuid-1234"      ]    },    "approval_required": true,    "approvers": {      "approvable_by_direct_managers": true,      "approvable_by_indirect_managers": false,      "employee_ids": [        "approver-member-uuid-1234"      ],      "group_ids": [        "approver-group-uuid-1234"      ],      "work_location_ids": [        "approver-work-location-uuid-1234"      ]    },    "additional_info_files": []  }'

Response

{  "data": {    "polling_key": "create_certification_abc123def456"  }}

Update Certification

This endpoint updates an existing certification within an organisation. The update operation is asynchronous, so a polling key is returned for tracking the operation status using the Polling Status API.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation

certification_iduuidrequired

The certification id

Request Body

namestring

Certification name (max 255 characters)

descriptionstring

Certification description

stateenum<string>

🇦🇺 AU

The regional state where the certification applies

territorystring

🌍 Global

Territory where certification applies

countystring

🇬🇧 UK

County where certification applies

due_within_daysinteger

Days to complete after assignment (min: 1, or null for one-off)

supporting_documentationboolean

Whether supporting documentation is required

certification_number_allowedboolean

Whether certification number is allowed

confirm_driving_offensesboolean

Enable the option for the assignee to confirm driving offenses when completing the certification

send_notify_update_emailboolean

Whether to send notification email on update

reset_member_licence_statusboolean

Whether to reset member licence status

use_expiry_dateboolean

Whether to use an expiry date for the certification

Note

The frequency_attributes field is disabled if this option is true

frequency_attributesobject

Frequency configuration for recurring certifications

assigneesobject

Configuration for assigning certifications

approval_requiredboolean

Whether approval is required for this certification

Note

The approvers field is disabled if this option is false

approversobject

Configuration for approving certifications

additional_info_filesstring[]

Additional info file URLs

Response Body

Returns a polling key that can be used to track the async update operation status

dataobject

polling_keystring

Redis key for polling the async operation status

certification_iduuid

The certification id

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "name": "Updated Name Goes Here",    "description": "Updated Description Goes Here",    "state": "TAS",    "due_within_days": 14,    "supporting_documentation": false,    "certification_number_allowed": false,    "confirm_driving_offenses": false,    "assignees": {      "assigned_to_all_organisation_members": false,      "assigned_to_all_organisation_contractors": true,      "employee_ids": [        "assignee-member-uuid-1234"      ],      "contractor_ids": [        "assignee-contractor-uuid-1234"      ],      "group_ids": [        "assignee-group-uuid-1234"      ],      "work_location_ids": [        "assignee-work-location-uuid-1234"      ]    },    "approval_required": true,    "approvers": {      "approvable_by_direct_managers": true,      "approvable_by_indirect_managers": true,      "employee_ids": [        "approver-member-uuid-1234"      ],      "group_ids": [        "approver-group-uuid-1234"      ],      "work_location_ids": [        "approver-work-location-uuid-1234"      ]    },    "use_expiry_date": false,    "frequency_attributes": {      "frequency": "renewing",      "repeat": "days",      "timer": 10    },    "additional_info_files": [],    "send_notify_update_email": false,    "reset_member_licence_status": false  }'

Response

{  "data": {    "polling_key": "update_certification_with_versioning_abc123def456",    "certification_id": "6538a2bb-2b34-4437-9a00-92af3dab5b59"  }}

Certification Polling Status

This endpoint retrieves the status of an async certification operation. Use the polling key returned from operations like Update Certification to track their progress.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/polling_status

Path Parameters

organisation_iduuidrequired

The ID of the organisation

Query Parameters

polling_keystringrequired

Polling key returned from certification modification endpoints (e.g., update-certification)

Response Body

Returns the current status of an async certification operation. Poll this endpoint to track the progress of operations like certification updates.

dataobject

polling_keystring

The polling key for tracking the async operation

statusstring

The result data from the operation (null if still processing)

processingboolean

Whether the operation is still processing

errorstring

Error message if the operation failed (null if successful or still processing)

Example

curl -X GET \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/polling_status" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "polling_key": "certifications_update_request_abc123def456",    "status": "Success",    "processing": false,    "error": ""  }}

Archive/Unarchive Certification

This endpoint archives or unarchives a certification based on the specified status.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id/archive_status

Path Parameters

organisation_iduuidrequired

The ID of the organisation

certification_iduuidrequired

The certification id

Request Body

statusbooleanrequired

Archive status: true to archive the certification, false to unarchive it

Response Body

Returns a 200 status on successful archive/unarchive. Returns 404 if certification not found, 403 if modification is forbidden, or 422 if validation errors occur.

dataobject

successboolean

Indicates if the certification was successfully archived or unarchived

Example

curl -X PATCH \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id/archive_status" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -H "Content-Type: application/json" \  -d '{    "status": true  }'

Response

{  "data": {    "success": true  }}

Delete Certification

This endpoint deletes a specific certification within an organisation asynchronously.

DELETE

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id

Path Parameters

organisation_iduuidrequired

The ID of the organisation

certification_iduuidrequired

The certification id

Response Body

Returns a polling key that can be used to track the async deletion status.

Note: This is a polling-based deletion process, meaning the actual deletion completion will be processed asynchronously. You may need to use Polling Status API to track the completion of the deletion process.

dataobject

polling_keystring

Polling key for tracking the async deletion status

Example

curl -X DELETE \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/:certification_id" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"

Response

{  "data": {    "polling_key": "certifications_delete_request_abc123def456"  }}

Upload Certification Files

Upload certification attachment files. The file URLs can then be passed to the additional_info_files field in Update Certification.

POST

https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/file_uploads

Path Parameters

organisation_iduuidrequired

The ID of the organisation

Request Body

filesfile[]required

Files to upload via multipart/form-data.

Note

Maximum 3 files per request, each up to 10 MB.
Allowed formats: JPG, JPEG, PNG, PDF, DOC, DOCX.

Response Body

Returns a list of successfully uploaded file details on HTTP 201.

dataobject

filesobject[]

List of uploaded file details

Example

curl -X POST \  "https://api.employmenthero.com/api/v1/organisations/:organisation_id/certifications/file_uploads" \  -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \  -F "files=/path/to/certificate.pdf"

Response

{  "data": {    "files": [      {        "id": "c580adfd-c0f6-4544-85a8-b366c4c79251",        "url": "https://cdn.employmenthero.com/files/cert.pdf",        "name": "certification.pdf"      }    ]  }}