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 }}Updates the accrued amount of up to 30 time off balances in a single atomic request. The entire batch either succeeds or is rejected: if any update fails, nothing is saved.
https:/api.employmenthero.com/api/v1/organisations/:organisation_id/employees/leave_balances/bulkPath Parameters
The ID of the organisation.
Request Body
List of time off balance updates to apply. Maximum 30 items per request.
Response Body
All updated time off balance objects. The entire batch is atomic: if any update fails, nothing is saved.
The updated time off balance objects, returned in the same order as the request updates.
Example
curl -X PATCH \ "https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/leave_balances/bulk" \ -H "Authorization: Bearer AUXJ3123xyrj123fdsjkl124aAJKQ" \ -H "Content-Type: application/json" \ -d '{ "updates": [ { "employee_id": "a98000b5-d27f-4dc2-adf8-e5ddaefc33be", "leave_balance_id": "c3e4f5a6-b7c8-9d0e-1f2a-3b4c5d6e7f8a", "accrued_amount": 12.5, "reason": "Annual policy adjustment" }, { "employee_id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a", "leave_balance_id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "accrued_amount": 8, "reason": "Year-end payout" } ] }'Response
{ "data": { "items": [ { "id": "c3e4f5a6-b7c8-9d0e-1f2a-3b4c5d6e7f8a", "leave_category_id": "f6a7b8c9-d0e1-2f3a-4b5c-6d7e8f9a0b1c", "leave_category_name": "Annual Leave", "unit_type": "hours", "accrued_amount": 12.5, "approved_leave": 0, "pending_leave": 0, "available_balance": 12.5 }, { "id": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b", "leave_category_id": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d", "leave_category_name": "Sick Leave", "unit_type": "hours", "accrued_amount": 8, "approved_leave": 0, "pending_leave": 0, "available_balance": 8 } ] }}