Employment HeroThis endpoint retrieves a list of all leave requests.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/leave_requestsPath Parameters
The ID of the organisation to retrieve
Query Parameters
The start date of the leave request (YYYY-MM-DD format)
The end date of the leave request (YYYY-MM-DD format)
Current page index
11Number of items per page
20100Response Body
A hash with a data property that contains an array of up to the limit of leave requests. Each entry in the array is a separate leave request object. If there are no more leave requests, the resulting array will be empty.
Note: Hours are calculated using the employee's typical working day hours. If the leave category is configured to use days as the unit type, the platform will automatically convert the hours to days based on the employee's typical working day configuration.
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The total amount of leave request, expressed in the unit specified by unit_type.
The unit used to measure the leave request.
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The leave balance amount of leave request.
The category name of leave request object. I.E "Annual Leave"
The reason of employee's leave request.
The ID of employee who requested to leave.
Array of objects specifying custom hours for specific dates
Supporting files attached to the leave request.
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/leave_requests" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "start_date": "2017-05-29T00:00:00+00:00", "end_date": "2017-05-29T00:00:00+00:00", "total_hours": 8, "total_units": 8, "unit_type": "hours", "comment": "The last working day", "status": "Approved", "leave_balance_amount": 0, "leave_category_name": "Annual Leave", "reason": "Vacation", "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ], "file_uploads": [ { "id": "c580adfd-c0f6-4544-85a8-b366c4c79251", "name": "medical_certificate.pdf", "url": "https://cdn.employmenthero.com/files/medical_certificate.pdf" } ] } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a specific leave request.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/leave_requests/:idPath Parameters
The ID of the organisation to retrieve
The ID of the leave request to retrieve
Response Body
Note: Hours are calculated using the employee's typical working day hours. If the leave category is configured to use days as the unit type, the platform will automatically convert the hours to days based on the employee's typical working day configuration.
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The total amount of leave request, expressed in the unit specified by unit_type.
The unit used to measure the leave request.
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The leave balance amount of leave request.
The category name of leave request object. I.E "Annual Leave"
The reason of employee's leave request.
The ID of employee who requested to leave.
Array of objects specifying custom hours for specific dates
Supporting files attached to the leave request.
Example
curl -X GET \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/leave_requests/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "start_date": "2017-05-29T00:00:00+00:00", "end_date": "2017-05-29T00:00:00+00:00", "total_hours": 8, "total_units": 8, "unit_type": "hours", "comment": "The last working day", "status": "Approved", "leave_balance_amount": 0, "leave_category_name": "Annual Leave", "reason": "Vacation", "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ], "file_uploads": [ { "id": "c580adfd-c0f6-4544-85a8-b366c4c79251", "name": "medical_certificate.pdf", "url": "https://cdn.employmenthero.com/files/medical_certificate.pdf" } ] }}This endpoint creates a new leave request for a specific employee. The endpoint supports custom hours per day configuration and will automatically fill in missing dates with the employee's typical working day hours.
Note: Dates within the start_date and end_date range that are not explicitly defined in the hours_per_day array will automatically use the employee's full typical working day hours. Hours are calculated using the employee's typical working day hours, and if the leave category is configured to use days as the unit type, the platform will automatically convert the hours to days.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requestsPath Parameters
The ID of the organisation to create the leave request
The ID of the employee to create the leave request for
Request Body
The category id of the leave request
The start date of the leave request (YYYY-MM-DD format)
The end date of the leave request (YYYY-MM-DD format)
The comment for the leave request
Array of objects specifying custom hours for specific dates
An array of file IDs obtained from the Upload Leave Request Files endpoint. Maximum 10 files per leave request.
Response Body
Returns the created leave request object with all details including the automatically calculated total hours and any auto-filled hours for dates not specified in the hours_per_day array.
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The total amount of leave request, expressed in the unit specified by unit_type.
The unit used to measure the leave request.
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The leave balance amount of leave request.
The category name of leave request object. I.E "Annual Leave"
The reason of employee's leave request.
The ID of employee who requested to leave.
Array of objects specifying custom hours for specific dates
Supporting files attached to the leave request.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "leave_category_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "start_date": "2025-12-25", "end_date": "2025-12-27", "comment": "Holiday vacation", "hours_per_day": [ { "date": "2025-12-25", "hours": 7.6 }, { "date": "2025-12-26", "hours": 7.6 } ], "file_upload_ids": [ "c580adfd-c0f6-4544-85a8-b366c4c79251" ] }'Response
{ "data": { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "start_date": "2017-05-29T00:00:00+00:00", "end_date": "2017-05-29T00:00:00+00:00", "total_hours": 8, "total_units": 8, "unit_type": "hours", "comment": "The last working day", "status": "Approved", "leave_balance_amount": 0, "leave_category_name": "Annual Leave", "reason": "Vacation", "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ], "file_uploads": [ { "id": "c580adfd-c0f6-4544-85a8-b366c4c79251", "name": "medical_certificate.pdf", "url": "https://cdn.employmenthero.com/files/medical_certificate.pdf" } ] }}Partially update an existing leave request for an employee. All request body fields are optional — only include the fields you wish to change. The leave request must not be in a processed state.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/:leave_request_idPath Parameters
The ID of the organisation.
The ID of the employee whose leave request is being updated.
The ID of the leave request to update.
Request Body
The start date of the leave request in YYYY-MM-DD format. Omit to keep the existing value.
The end date of the leave request in YYYY-MM-DD format. Omit to keep the existing value.
The UUID of the leave category. Omit to keep the existing category.
A comment or note for the leave request. Omit to keep the existing comment.
Array of objects specifying custom hours for specific dates. Omit to keep the existing hours per day configuration.
An array of file IDs obtained from the Upload Leave Request Files endpoint. Replaces all existing attachments. Pass an empty array to remove all attachments. Omit to keep the existing attachments. Maximum 10 files per leave request.
Response Body
Returns the updated leave request object with all recalculated fields including total hours and units.
Unique identifier for the object.
The start date of your employee leave request.
The end date of your employee leave request.
The total hours of leave request.
The total amount of leave request, expressed in the unit specified by unit_type.
The unit used to measure the leave request.
The comment of the leave request if an owner or admin has entered a notation
The status of leave request.
The leave balance amount of leave request.
The category name of leave request object. I.E "Annual Leave"
The reason of employee's leave request.
The ID of employee who requested to leave.
Array of objects specifying custom hours for specific dates
Supporting files attached to the leave request.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/:leave_request_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "start_date": "2025-08-05", "end_date": "2025-08-08", "comment": "Updated holiday dates", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ], "file_upload_ids": [ "c580adfd-c0f6-4544-85a8-b366c4c79251" ] }'Response
{ "data": { "id": "724ec1f7-ebe9-4af6-84bf-7f071167007a", "start_date": "2017-05-29T00:00:00+00:00", "end_date": "2017-05-29T00:00:00+00:00", "total_hours": 8, "total_units": 8, "unit_type": "hours", "comment": "The last working day", "status": "Approved", "leave_balance_amount": 0, "leave_category_name": "Annual Leave", "reason": "Vacation", "employee_id": "0139ebb7-6f3e-4bc0-954e-9e50614fccd1", "hours_per_day": [ { "date": "2014-08-05", "hours": 7.6 }, { "date": "2014-08-06", "hours": 7.6 }, { "date": "2014-08-07", "hours": 7.6 }, { "date": "2014-08-08", "hours": 7.6 } ], "file_uploads": [ { "id": "c580adfd-c0f6-4544-85a8-b366c4c79251", "name": "medical_certificate.pdf", "url": "https://cdn.employmenthero.com/files/medical_certificate.pdf" } ] }}Permanently delete an existing leave request for an employee. The leave request must not be in a processed state and must belong to the specified employee. This action cannot be undone.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/:leave_request_idPath Parameters
The ID of the organisation.
The ID of the employee whose leave request is being deleted.
The ID of the leave request to permanently delete.
Response Body
Returns HTTP 204 No Content on success. This action is permanent and cannot be undone.
Example
curl -X DELETE \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/:leave_request_id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
This endpoint does not return a response body.
Upload supporting files (such as medical certificates) for a leave request. Returns file IDs that can be passed to the Create Leave Request endpoint via the file_upload_ids field.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/file_uploadsPath Parameters
The ID of the organisation.
The ID of the employee to upload files for.
Request Body
Files to upload via multipart/form-data.
Note
Allowed formats: PDF, JPG, JPEG, PNG, DOCX.
Response Body
Returns a list of successfully uploaded file details on HTTP 201.
List of uploaded file details.
Example
curl -X POST \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/file_uploads" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -F "files=/path/to/medical_certificate.pdf"Response
{ "data": { "files": [ { "id": "c580adfd-c0f6-4544-85a8-b366c4c79251", "url": "https://cdn.employmenthero.com/files/leave-attachment.pdf", "name": "medical_certificate.pdf" } ] }}