Employment HeroThis endpoint retrieves a list of all time off requests, optionally filtered by status, leave category, and date range.
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 time off request (YYYY-MM-DD format)
The end date of the time off request (YYYY-MM-DD format)
The status of the time off requests. Multiple values can be provided, up to a maximum of 100. Providing more than 100 returns 422.
The leave category of the time off requests. Returns no results for a sensitive leave category the caller cannot view (the caller's own requests are still returned), and requests recorded against a payroll pay category never match.
Only return time off requests for these employees. Up to 100 IDs; more than 100 returns 422. IDs that do not match any employee return no results.
Only return time off requests in these leave categories. Up to 100 IDs; more than 100 returns 422. Sensitive leave categories the caller cannot view, and IDs that do not match any category, return no results.
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 time off requests. Each entry in the array is a separate time off request object. If there are no more time off 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 time off request.
The end date of your employee time off request.
The total hours of time off request.
The total amount of time off request, expressed in the unit specified by unit_type.
The unit used to measure the time off request.
The comment of the time off request if an owner or admin has entered a notation
The status of time off request.
The leave balance amount of time off request.
The category name of time off request object. I.E "Annual Leave"
The reason of employee's time off request.
The ID of employee who requested time off.
Array of objects specifying custom hours for specific dates
Supporting files attached to the leave request.
The ID of the leave category of the time off request. null when the time off request is masked because it belongs to a sensitive leave category the caller cannot view, and for requests recorded against a payroll pay category.
When the time off request was created (RFC 3339).
When the time off request was last updated (RFC 3339).
When the time off request was last edited (RFC 3339), or null if it has never been edited.
Whether the time off request is open-ended.
Which half of the day a half-day time off request covers, or null when it is not a half-day request.
The start time of a part-day time off request in HH:MM format, or null when none is set.
The end time of a part-day time off request in HH:MM format, or null when none is set.
Whether the time off request has been processed through payroll.
When the time off request was processed through payroll (RFC 3339), or null if no processed time is recorded.
The members who approved the time off request, ordered by approval time with duplicates removed. Empty when nobody has approved it and when the time off request is masked.
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" } ], "leave_category_id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "created_at": "2017-05-20T02:15:29+00:00", "updated_at": "2017-05-22T09:30:00+00:00", "edited_at": null, "is_open_ended": false, "day_part": null, "start_time": null, "end_time": null, "processed": true, "processed_at": "2017-06-02T03:00:00+00:00", "approvers": [ { "id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b", "name": "Alex Example" } ] } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint retrieves a specific time off 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 time off 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 time off request.
The end date of your employee time off request.
The total hours of time off request.
The total amount of time off request, expressed in the unit specified by unit_type.
The unit used to measure the time off request.
The comment of the time off request if an owner or admin has entered a notation
The status of time off request.
The leave balance amount of time off request.
The category name of time off request object. I.E "Annual Leave"
The reason of employee's time off request.
The ID of employee who requested time off.
Array of objects specifying custom hours for specific dates
Supporting files attached to the leave request.
The ID of the leave category of the time off request. null when the time off request is masked because it belongs to a sensitive leave category the caller cannot view, and for requests recorded against a payroll pay category.
When the time off request was created (RFC 3339).
When the time off request was last updated (RFC 3339).
When the time off request was last edited (RFC 3339), or null if it has never been edited.
Whether the time off request is open-ended.
Which half of the day a half-day time off request covers, or null when it is not a half-day request.
The start time of a part-day time off request in HH:MM format, or null when none is set.
The end time of a part-day time off request in HH:MM format, or null when none is set.
Whether the time off request has been processed through payroll.
When the time off request was processed through payroll (RFC 3339), or null if no processed time is recorded.
The members who approved the time off request, ordered by approval time with duplicates removed. Empty when nobody has approved it and when the time off request is masked.
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" } ], "leave_category_id": "c7d8e9f0-1a2b-4c3d-8e4f-5a6b7c8d9e0f", "created_at": "2017-05-20T02:15:29+00:00", "updated_at": "2017-05-22T09:30:00+00:00", "edited_at": null, "is_open_ended": false, "day_part": null, "start_time": null, "end_time": null, "processed": true, "processed_at": "2017-06-02T03:00:00+00:00", "approvers": [ { "id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b", "name": "Alex Example" } ] }}This endpoint retrieves a list of time off requests belonging to a specific employee, optionally filtered by status, leave category, and date range.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requestsPath Parameters
The ID of the organisation to retrieve
The ID of the employee whose time off requests to retrieve
Query Parameters
The status of the time off requests. Multiple values can be provided.
The start date of the time off request (YYYY-MM-DD format)
The end date of the time off request (YYYY-MM-DD format)
The leave category of the time off requests
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 time off requests belonging to the specified employee. Each entry in the array is a separate time off request object. If there are no matching time off 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 time off request.
The end date of your employee time off request.
The total hours of time off request.
The total amount of time off request, expressed in the unit specified by unit_type.
The unit used to measure the time off request.
The comment of the time off request if an owner or admin has entered a notation
The status of time off request.
The leave balance amount of time off request.
The category name of time off request object. I.E "Annual Leave"
The reason of employee's time off request.
The ID of employee who requested time off.
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/employees/:employee_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 creates a new time off 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 time off type 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 time off request
The ID of the employee to create the time off request for
Request Body
The category id of the time off request
The start date of the time off request (YYYY-MM-DD format)
The end date of the time off request (YYYY-MM-DD format)
The comment for the time off 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 time off 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 time off request.
The end date of your employee time off request.
The total hours of time off request.
The total amount of time off request, expressed in the unit specified by unit_type.
The unit used to measure the time off request.
The comment of the time off request if an owner or admin has entered a notation
The status of time off request.
The leave balance amount of time off request.
The category name of time off request object. I.E "Annual Leave"
The reason of employee's time off request.
The ID of employee who requested time off.
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 time off request in YYYY-MM-DD format. Omit to keep the existing value.
The end date of the time off 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 time off 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 time off request object with all recalculated fields including total hours and units.
Unique identifier for the object.
The start date of your employee time off request.
The end date of your employee time off request.
The total hours of time off request.
The total amount of time off request, expressed in the unit specified by unit_type.
The unit used to measure the time off request.
The comment of the time off request if an owner or admin has entered a notation
The status of time off request.
The leave balance amount of time off request.
The category name of time off request object. I.E "Annual Leave"
The reason of employee's time off request.
The ID of employee who requested time off.
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" } ] }}Approve an employee's leave request.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/:leave_request_id/approvePath Parameters
The ID of the organisation.
The ID of the employee who owns the time off request.
The ID of the time off request to approve.
Response Body
Returns the approved time off request object with updated status.
Unique identifier for the object.
The start date of your employee time off request.
The end date of your employee time off request.
The total hours of time off request.
The total amount of time off request, expressed in the unit specified by unit_type.
The unit used to measure the time off request.
The comment of the time off request if an owner or admin has entered a notation
The status of time off request.
The leave balance amount of time off request.
The category name of time off request object. I.E "Annual Leave"
The reason of employee's time off request.
The ID of employee who requested time off.
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/:leave_request_id/approve" \ -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" } ] }}Decline an employee's leave request.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_requests/:leave_request_id/declinePath Parameters
The ID of the organisation.
The ID of the employee who owns the time off request.
The ID of the time off request to decline.
Request Body
Optional reason for declining the time off request.
Response Body
Returns the declined time off request object with updated status.
Unique identifier for the object.
The start date of your employee time off request.
The end date of your employee time off request.
The total hours of time off request.
The total amount of time off request, expressed in the unit specified by unit_type.
The unit used to measure the time off request.
The comment of the time off request if an owner or admin has entered a notation
The status of time off request.
The leave balance amount of time off request.
The category name of time off request object. I.E "Annual Leave"
The reason of employee's time off request.
The ID of employee who requested time off.
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/:leave_request_id/decline" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "reason": "Insufficient staffing levels during this period." }'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" } ] }}