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

An empty result does not mean the employee has no time off. A caller who lacks permission to view another employee's time off receives an empty array with HTTP 200, which is indistinguishable from an employee who genuinely has no assigned categories. Do not report that someone has no balance or no time off remaining on the basis of an empty response. Calling this endpoint for an employee the caller can definitely read (their own record) as a control confirms only that the endpoint works for this caller; it does not establish that an empty result for someone else is a permission block, because a readable employee with no assigned policies also returns an empty array. To distinguish the two, call list-employee-time-off-policies-v1-1 for the same employee: a 403 naming the required permission means the caller has no access, while a 200 means the record is readable and genuinely has no policies assigned. If that endpoint is also inaccessible, report that it cannot be determined rather than choosing one interpretation.

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