Sign in

v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB
Time Off
Public API

Get Time Off Balance

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.

OAuth Scopes: time_off

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

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