BAbamboohr
Time Off
Public API

Get Time Off Balance

Changed on

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

get/api/v1/employees/{employeeId}/time_off/calculator

Request

Path parameters

employeeIdstring required

The internal employee ID of the employee whose time off balances are returned.

Query parameters

endstring date

The date to calculate the time off balance as of, in YYYY-MM-DD format. Defaults to company today if not provided. Example: use a future date to project balance.

precisioninteger

Number of decimal places for balance and usedYearToDate values. Minimum 0, maximum 4. Defaults to 2.

Headers

AcceptHeaderParameter'application/xml' | 'application/json'

This endpoint can produce either JSON or XML.

Response

An array of time off balance entries, one per assigned time off type.

timeOffTypestring

The ID of the time off type.

namestring

The name of the time off type.

unitsstring

The unit of measurement for the balance (e.g. 'hours' or 'days').

balancestring

The calculated time off balance as of the specified date, rounded using precision.

endstring date

The date the balance was calculated as of, in YYYY-MM-DD format.

policyType'accruing' | 'discretionary' | 'manual'

The type of time off policy assigned to the employee for this time off type.

usedYearToDatestring

The amount of time off used year-to-date as of the specified date, rounded using precision.

Example response

[
  {
    "units": "hours",
    "balance": "24.50",
    "usedYearToDate": "12.25"
  }
]

Changes