Employment HeroThis endpoint retrieves a list of all certifications assigned to a specific employee.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certificationsPath Parameters
The ID of the organisation to retrieve
The ID of the employee to retrieve
Query Parameters
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an item array of up to limit employee certifications. Each entry in the array is a separate employee certification object. If there are no more employee certification, the resulting array will be empty.
The employee certification id
The certification name of employee certification
The certification id of employee certification
The certification type of employee certification
The expiry date of employee certification
The completion date of employee certification
The certification driver problem of employee certification
The certification driver details of employee certification
The status of the certification. One of: Outstanding, In review, Expired. For approved/declined certifications, includes the acknowledger name and RFC3339 timestamp, e.g. Approved by Jane Smith on 2025-01-01T00:00:00+00:00 or Declined by Jane Smith on 2025-01-01T00:00:00+00:00
The certification reason of employee certification
The certification number of the employee certification
The previous status of the employee certification
The due date of the employee certification
The date the certification was assigned. Null for legacy records
The document signature id associated with the certification
The person who approved or declined the certification. Null if not yet approved or declined
Documents attached to the employee certification
Indicates who assigned this certification. Only present when the heroforce_induction_flow_certifications_release feature flag is enabled for the organisation.
The geographical area type for this certification, based on the user's organisation country. county for UK organisations, state for AU organisations, territory for all others.
Actions the requester is permitted to perform on this certification. Null if no requester context
The certification associated with this employee certification
Current page index
11Number of items per page
20100Total items
Total pages
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certifications" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "3128a2bb-2b34-4437-9a00-92af3dab5b59", "name": "Full-disk encryption", "certification_id": "6538a2bb-2b34-4437-9a00-92af3dab5b33", "type": "Check", "expiry_date": "2026-03-31T00:00:00+00:00", "completion_date": "2026-03-01T00:00:00+00:00", "driver_problem": true, "driver_details": "Employee has 2 speeding offenses in the last year", "status": "Approved by Jane Smith on 2025-01-01T00:00:00+00:00", "reason": null, "certification_number": "CERT-001", "previous_status": "In review", "due_date": "2025-06-01T00:00:00+00:00", "assigned_at": "2025-01-01T00:00:00+00:00", "document_signature_id": null, "acknowledger": { "acknowledger": "Jane Smith", "acknowledged_at": "2025-01-01T00:00:00+00:00" }, "documents": [ { "id": "f1e2d3c4-b5a6-7890-fedc-ba9876543210", "created_at": "2025-01-01T00:00:00+00:00", "remote_url": "https://cdn.employmenthero.com/files/certificate.pdf", "identifier": "certificate.pdf" } ], "area_type": "state", "permissions": { "approve": true, "decline": false, "delete_documents": true }, "licence": { "id": "6538a2bb-2b34-4437-9a00-92af3dab5b33", "name": "Full-disk encryption", "confirm_driving_offenses": false, "use_expiry_date": true, "supporting_documentation": true, "additional_info_files": [], "state": "NSW", "territory": null, "county": null, "description": "Employees must complete full-disk encryption setup", "certification_number_allowed": true, "mandatory": true } } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}Upload one or more supporting documents for an employee's certification. Each uploaded file receives a unique id that can be passed to the documents_to_add field in Update Employee Certification.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certifications/file_uploadsPath Parameters
The ID of the organisation
The ID of the employee to upload documents for
Request Body
Files to upload via multipart/form-data.
Note
Allowed formats: PDF, JPG, JPEG, PNG, DOC, DOCX.
Response Body
A data object containing a files array of uploaded file objects. Files are stored immediately but not yet associated with any certification record.
List of uploaded file details
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certifications/file_uploads" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -F "files=/path/to/new-certificate.pdf"Response
{ "data": { "files": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "url": "https://cdn.employmenthero.com/files/new-certificate.pdf", "name": "new-certificate.pdf" } ] }}This endpoint updates the completion details for an employee's assigned certification record. Fields may be required depending on the certification type — see field descriptions for details.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certifications/:idPath Parameters
The ID of the organisation
The ID of the employee
The ID of the employee's certification record. Obtain from Get All Employee Certification Details
Request Body
The date the employee completed or obtained this certification
The date the certification expires. Required when licence.use_expiry_date is true
The employee's certificate number. Required when licence.certification_number_allowed is true
IDs of existing certification document records to retain. Documents not included in this list will be removed. Both documents_to_keep and documents_to_add are required when licence.supporting_documentation is true, and at least one must be non-empty. All provided IDs must belong to this certification record.
File IDs obtained from Upload Employee Certification Files to attach as new documents. Both documents_to_keep and documents_to_add are required when licence.supporting_documentation is true, and at least one must be non-empty. If duplicate IDs are provided, only one document will be added per unique ID.
Whether the employee declares previous driving offences, accidents, or licence cancellations. Required when licence.confirm_driving_offenses is true
Details of the offences, accidents, or cancellations. Required when driver_problem is true
Response Body
Returns the updated employee certification detail.
The employee certification id
The certification name of employee certification
The certification id of employee certification
The certification type of employee certification
The expiry date of employee certification
The completion date of employee certification
The certification driver problem of employee certification
The certification driver details of employee certification
The status of the certification. One of: Outstanding, In review, Expired. For approved/declined certifications, includes the acknowledger name and RFC3339 timestamp, e.g. Approved by Jane Smith on 2025-01-01T00:00:00+00:00 or Declined by Jane Smith on 2025-01-01T00:00:00+00:00
The certification reason of employee certification
The certification number of the employee certification
The previous status of the employee certification
The due date of the employee certification
The date the certification was assigned. Null for legacy records
The document signature id associated with the certification
The person who approved or declined the certification. Null if not yet approved or declined
Documents attached to the employee certification
Indicates who assigned this certification. Only present when the heroforce_induction_flow_certifications_release feature flag is enabled for the organisation.
The geographical area type for this certification, based on the user's organisation country. county for UK organisations, state for AU organisations, territory for all others.
Actions the requester is permitted to perform on this certification. Null if no requester context
The certification associated with this employee certification
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/certifications/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "completion_date": "2024-06-15", "expiry_date": "2026-06-15", "certification_number": "WWCC-123456", "documents_to_keep": [ "f1e2d3c4-b5a6-7890-fedc-ba9876543210" ], "documents_to_add": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] }'Response
{ "data": { "id": "3128a2bb-2b34-4437-9a00-92af3dab5b59", "name": "Full-disk encryption", "certification_id": "6538a2bb-2b34-4437-9a00-92af3dab5b33", "type": "Check", "expiry_date": "2026-03-31T00:00:00+00:00", "completion_date": "2026-03-01T00:00:00+00:00", "driver_problem": true, "driver_details": "Employee has 2 speeding offenses in the last year", "status": "Approved by Jane Smith on 2025-01-01T00:00:00+00:00", "reason": null, "certification_number": "CERT-001", "previous_status": "In review", "due_date": "2025-06-01T00:00:00+00:00", "assigned_at": "2025-01-01T00:00:00+00:00", "document_signature_id": null, "acknowledger": { "acknowledger": "Jane Smith", "acknowledged_at": "2025-01-01T00:00:00+00:00" }, "documents": [ { "id": "f1e2d3c4-b5a6-7890-fedc-ba9876543210", "created_at": "2025-01-01T00:00:00+00:00", "remote_url": "https://cdn.employmenthero.com/files/certificate.pdf", "identifier": "certificate.pdf" }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "created_at": "2025-01-02T00:00:00+00:00", "remote_url": "https://cdn.employmenthero.com/files/new-certificate.pdf", "identifier": "new-certificate.pdf" } ], "area_type": "state", "permissions": { "approve": true, "decline": false, "delete_documents": true }, "licence": { "id": "6538a2bb-2b34-4437-9a00-92af3dab5b33", "name": "Full-disk encryption", "confirm_driving_offenses": false, "use_expiry_date": true, "supporting_documentation": true, "additional_info_files": [], "state": "NSW", "territory": null, "county": null, "description": "Employees must complete full-disk encryption setup", "certification_number_allowed": true, "mandatory": true } }}