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
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 } ] } ], "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
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 } ] }}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
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
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 } ] }'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 } ] }}