Employment HeroThis endpoint retrieves a paginated list of leave 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 leave 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 leave balances. Each entry in the array is a separate leave balance object. If there are no more leave balances, the resulting array will be empty.
Unique identifier for the leave balance.
The ID of the associated leave category.
The name of the associated leave category (e.g. "Annual Leave").
The unit type for this leave 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 leave 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 leave balance to update
The ID of the leave 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 leave balance object with the new accrued amount.
Unique identifier for the leave balance.
The ID of the associated leave category.
The name of the associated leave category (e.g. "Annual Leave").
The unit type for this leave 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 }}