Returns time off balances for an employee across all assigned categories as of a given date. Each category's balance is calculated by summing all historical balance events (accruals, manual adjustments, used time off, and carry-over events) plus any future accruals and adjustments up to the specified date. To get current balances, pass today's date; to project future balances, pass a future date. Response defaults to XML unless Accept: application/json is provided.

This endpoint does not accept the 0 self sentinel. Unlike Get Employee (get-employee), passing 0 as employeeId returns 404 with an empty body and the header x-bamboohr-error-message: Employee not found. To read the authenticated caller's own balances, first resolve their internal employee ID with get-employee using the id 0, then call this endpoint with that ID.

Permissions. Access is gated on the same Time Off tab view permission the web application uses. That permission is configured per access level and is not implied by the reporting structure: being an employee's manager does not by itself grant it, and a manager may receive 403 for their own direct reports. A caller without permission for the target employee receives an explicit 403 rather than an empty success, so the two cases are distinguishable: a 403 means access was denied, while an empty array with 200 means the employee has no assigned policies among the time off types this caller can view. Do not read a 403 as the employee having no time off, and do not read an empty array as a permission problem.

Because the categories returned are limited to the time off types the caller can view for that employee, two callers can legitimately receive different subsets for the same person. Treat the returned set as what this caller may see, not as the employee's complete policy list. list-employee-time-off-policies-v1-1 is the companion endpoint for the underlying assignments and is gated on the same permission.

A category returning 0.00 is not an error and does not necessarily mean the time cannot be requested. Discretionary policies (for example Bereavement or FMLA) are granted as needed rather than accrued, so they normally report a zero balance while still being available to request. Use policyType to distinguish accruing from discretionary before characterizing a zero.

OAuth Scopes: time_off