Employment HeroThis endpoint retrieves a paginated list of time off balances for a specific employee within an organisation.
Note: This endpoint is only available for organisations using HR Leave with Leave Balance data. Payroll-connected organisations are not yet supported.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_balancesPath Parameters
The ID of the organisation to retrieve
The ID of the employee whose time off balances to retrieve
Query Parameters
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 balances. Each entry in the array is a separate time off balance object. If there are no more time off balances, the resulting array will be empty.
Unique identifier for the time off balance.
The ID of the associated leave category.
The name of the associated leave category (e.g. "Annual Leave").
The unit type for this time off balance (e.g. days, hours).
The total accrued leave amount for this category.
The total amount of approved leave taken against this balance.
The total amount of pending (not yet approved) leave requests.
The available leave balance, calculated as the accrued amount minus approved leave.
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_balances" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ"Response
{ "data": { "items": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "leave_category_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "leave_category_name": "Annual Leave", "unit_type": "days", "accrued_amount": 20, "approved_leave": 5, "pending_leave": 2, "available_balance": 15 } ], "page_index": 1, "item_per_page": 20, "total_items": 1, "total_pages": 1 }}This endpoint updates the accrued amount of a specific time off balance for an employee.
Note: This endpoint is only available for organisations using HR Leave with Leave Balance data. Payroll-connected organisations are not supported.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_balances/:idPath Parameters
The ID of the organisation
The ID of the employee whose time off balance to update
The ID of the time off balance to update
Request Body
The new accrued leave balance amount to set.
The reason for this adjustment (used for audit trail).
Response Body
Returns the updated time off balance object with the new accrued amount.
Unique identifier for the time off balance.
The ID of the associated leave category.
The name of the associated leave category (e.g. "Annual Leave").
The unit type for this time off balance (e.g. days, hours).
The total accrued leave amount for this category.
The total amount of approved leave taken against this balance.
The total amount of pending (not yet approved) leave requests.
The available leave balance, calculated as the accrued amount minus approved leave.
Example
curl -X PUT \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_balances/:id" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "accrued_amount": 22.5, "reason": "Manual adjustment approved by HR" }'Response
{ "data": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "leave_category_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "leave_category_name": "Annual Leave", "unit_type": "days", "accrued_amount": 20, "approved_leave": 5, "pending_leave": 2, "available_balance": 15 }}