Employment HeroThis endpoint retrieves a list of all time off 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 time off request (YYYY-MM-DD format)
The end date of the time off 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 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
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 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
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 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
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
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 } ] }}