Time Off Balance

Get Time Off Balances

This 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.

GET

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_balances

Path Parameters

organisation_iduuidrequired

The ID of the organisation to retrieve

employee_iduuidrequired

The ID of the employee whose time off balances to retrieve

Query Parameters

leave_category_idsuuid[]

Only return time off balances in these leave categories. Up to 100 IDs; more than 100 returns 422.

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

Response 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.

Balances in sensitive leave categories are omitted when the caller cannot view the employee's sensitive leave.

dataobject

itemsobject[]

iduuid

Unique identifier for the time off balance.

leave_category_iduuid

The ID of the associated leave category.

leave_category_namestring

The name of the associated leave category (e.g. "Annual Leave").

unit_typestring

The unit type for this time off balance (e.g. days, hours).

accrued_amountnumber

The total accrued leave amount for this category.

approved_leavenumber

The total amount of approved leave taken against this balance.

pending_leavenumber

The total amount of pending (not yet approved) leave requests.

available_balancenumber

The available leave balance, calculated as the accrued amount minus approved leave.

employee_iduuid

The ID of the employee the time off balance belongs to.

updated_atdatetime

When the time off balance was last updated (RFC 3339).

projected_accrualnumber

The leave accrued since the last payslip, projected to projection_as_at_date. null when a projection does not apply to the employee or could not be calculated.

projection_as_at_datestring

The date the projected_accrual was calculated for (YYYY-MM-DD format), or null when there is no projection.

page_indexnumber

Current page index

Default1

Min1

item_per_pagenumber

Number of items per page

Default20

Max100

total_itemsnumber

Total items

total_pagesnumber

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,        "employee_id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",        "updated_at": "2026-08-10T04:01:53+00:00",        "projected_accrual": 1.25,        "projection_as_at_date": "2026-08-10"      }    ],    "page_index": 1,    "item_per_page": 20,    "total_items": 1,    "total_pages": 1  }}

Update Time Off Balance

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.

PUT

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/:employee_id/leave_balances/:id

Path Parameters

organisation_iduuidrequired

The ID of the organisation

employee_iduuidrequired

The ID of the employee whose time off balance to update

iduuidrequired

The ID of the time off balance to update

Request Body

accrued_amountnumberrequired

The new accrued leave balance amount to set.

reasonstringrequired

The reason for this adjustment (used for audit trail).

Response Body

Returns the updated time off balance object with the new accrued amount.

dataobject

iduuid

Unique identifier for the time off balance.

leave_category_iduuid

The ID of the associated leave category.

leave_category_namestring

The name of the associated leave category (e.g. "Annual Leave").

unit_typestring

The unit type for this time off balance (e.g. days, hours).

accrued_amountnumber

The total accrued leave amount for this category.

approved_leavenumber

The total amount of approved leave taken against this balance.

pending_leavenumber

The total amount of pending (not yet approved) leave requests.

available_balancenumber

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  }}

Bulk Update Time Off Balances

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.

PATCH

https://api.employmenthero.com/api/v1/organisations/:organisation_id/employees/leave_balances/bulk

Path Parameters

organisation_iduuidrequired

The ID of the organisation.

Request Body

updatesobject[]required

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.

dataobject

itemsobject[]

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      }    ]  }}