To fetch a worker’s live and future-projected absence balances accurately in Workday, call GET /balances?worker={worker_WID}&effective={YYYY-MM-DD} in the absenceManagement/v5 REST API, paired with GET /workers/{ID}/eligibleAbsenceTypes to map bookable Time Off Types to their underlying Time Off Plans and unit types (Hours or Days). Relying solely on stored-balance WQL tables or static Worker XML snapshots returns stale figures whenever accruals, carryover boundaries, or pending requests sit between the last stored snapshot and the target date.
Workday exposes absence eligibility and balance data across four distinct interfaces—absenceManagement/v5 REST, common/v1 REST, Absence_Management SOAP, and Workday Query Language (WQL). Selecting the right surface depends on whether you are answering an employee’s real-time “How much PTO will I have in August?” question or auditing period-by-period balance overrides.
Comparing the Four Workday Absence Balance Surfaces
| API Surface | Primary Endpoint / Operation / Data Source | Live As-Of Projection? | Best Use Case & Security Domain (Time Off and Leave Scope) |
|---|---|---|---|
API SurfaceAbsence REST (v5) |
Primary Endpoint / Operation / Data SourceGET /balances & GET /workers/{ID}/eligibleAbsenceTypes |
Live As-Of Projection?Yes (effective=YYYY-MM-DD) |
Best Use Case & Security Domain ( Time Off and Leave Scope)Employee self-service screens and AI lookups across Time Off Plans, Absence Tables, and Leave Entitlements (Self-Service: Time Off Balances, Self-Service: Leave of Absence Entitlements). |
API SurfaceCommon REST (v1) |
Primary Endpoint / Operation / Data SourceGET /workers/{ID}/timeOffPlans |
Live As-Of Projection?Current date only | Best Use Case & Security Domain ( Time Off and Leave Scope)Quick lookup of Time Off Plan balances and unit types assigned to a single worker (Self-Service: Time Off Balances, Worker Data: Time Off (Time Off Balances Manager View)). |
| API SurfaceAbsence SOAP | Primary Endpoint / Operation / Data SourceGet_Time_Off_Plan_Balances & Get_Absence_Inputs |
Live As-Of Projection?Snapshot / Period boundary | Best Use Case & Security Domain ( Time Off and Leave Scope)Extracting stored plan balances, manual accrual adjustments (Put_Absence_Input), and balance overrides (Get_Override_Balances). |
| API SurfaceWorkday Query Language (WQL) | Primary Endpoint / Operation / Data SourcetimeOffPlanCalculatedAndOverrideBalancesForWorker & timeOffResultsByPeriodForWorkers |
Live As-Of Projection?Stored / Period rows | Best Use Case & Security Domain ( Time Off and Leave Scope)Reporting historical period accruals, overrides, and recalculated snapshots across periods. |
Querying Live and Future Balances with absenceManagement/v5
1. Filter GET /balances by Worker, Category, and Effective Date
GET /balances in absenceManagement/v5 returns every eligible balance pool for a worker across three Workday absence categories. Pass worker (required in practice for single-user queries), effective (YYYY-MM-DD), and optionally category:
- Time Off:
7bd6531c90c100016d4b06f2b8a07ce - Leave of Absence Type:
17bd6531c90c100016d74f8dfae007d0 - Absence Table:
17bd6531c90c100016da3f5b554007d2
GET /ccx/api/absenceManagement/v5/{tenant}/balances?worker=3aa5550b7fe348b98d7b5741afc6f534&category=7bd6531c90c100016d4b06f2b8a07ce&effective=2026-11-15 HTTP/1.1
Authorization: Bearer <user_delegated_access_credential>
Accept: application/jsonA typical response returns one object per eligible plan (and per position when the tenant uses position-based Time Off Plans):
{
"total": 2,
"data": [
{
"id": "842800d7bb021000741e5d56eac70162",
"worker": {
"id": "3aa5550b7fe348b98d7b5741afc6f534",
"descriptor": " Elena Rostova"
},
"absencePlan": {
"id": "4c91b208e1f3100018a29014bc8d0041",
"descriptor": "US Salaried PTO Plan"
},
"category": {
"id": "7bd6531c90c100016d4b06f2b8a07ce",
"descriptor": "Time Off"
},
"quantity": 92.5,
"unit": {
"id": "c4630594446c11de98360015c5e6daf6",
"descriptor": "Hours"
},
"effectiveDate": "2026-11-15",
"position": {
"id": "6f21a904d8c1100012b34099ef120088",
"descriptor": "P-00412 Senior Financial Analyst"
}
},
{
"id": "842800d7bb021000741e5d56eac70199",
"worker": {
"id": "3aa5550b7fe348b98d7b5741afc6f534",
"descriptor": "Elena Rostova"
},
"absencePlan": {
"id": "5d82c319f2a4100019b30125cd9e0052",
"descriptor": "California Paid Sick Plan"
},
"category": {
"id": "7bd6531c90c100016d4b06f2b8a07ce",
"descriptor": "Time Off"
},
"quantity": 32.0,
"unit": {
"id": "c4630594446c11de98360015c5e6daf6",
"descriptor": "Hours"
},
"effectiveDate": "2026-11-15"
}
]
}2. Reconcile absencePlan (Balances) with timeOffType (Booking)
A classic Workday integration mistake is confusing a Time Off Plan with a Time Off Type:
- Balances live on the Time Off Plan (
US Salaried PTO Plan), because multiple Time Off Types (for example,Vacation,Personal Day, andEmergency Unplanned PTO) often draw down from the same shared Time Off Plan balance pool. - Requests (
POST /workers/{ID}/requestTimeOff) book against a Time Off Type returned byGET /workers/{ID}/eligibleAbsenceTypes—or against an Absence Table that cascades across multiple tiered plans when the first tier hits zero. - Non-Balance Plans: Time Off Plans configured with Track Balance disabled (such as
BereavementorJury Duty) allow workers to request eligible Time Off Types even though no accrued balance pool exists inGET /balances. Always display both tracked balances (GET /balances) and untracked eligible absence types (GET /workers/{ID}/eligibleAbsenceTypes) when building a request screen.
Auditing Period Accruals and Overrides via WQL and SOAP
When an HR partner or employee asks why their balance equals 92.5 hours—checking whether a manual adjustment, carryover cap, or balance override occurred—REST GET /balances only gives the net result. Use WQL (POST /wql/v1/data) or Absence_Management SOAP for the underlying ledger:
SELECT
timeOffPlan,
timeOffPlanBalanceDate,
timeOffPlanBalanceUnits,
unitOfTime,
override,
calculatedAccruals,
comment
FROM timeOffPlanCalculatedAndOverrideBalancesForWorker(
workerForCalculatedAndOverrideBalanceReport = '3aa5550b7fe348b98d7b5741afc6f534'
)
ORDER BY timeOffPlanBalanceDate DESCAnd to inspect period-by-period accruals and deductions across a worker’s Period Schedule, query timeOffResultsByPeriodForWorkers in WQL or call SOAP Get_Absence_Inputs (which extracts manual accrual adjustments and plan overrides entered via Put_Absence_Input) and Get_Time_Off_Plan_Balances in the Absence_Management web service. Keep in mind that Get_Time_Off_Plan_Balances reads stored balance checkpoints (Manually Schedule Storage of Time Off Balances); if a retroactive job change altered FTE prior to the stored checkpoint, an administrator must run Recalculate Balances for Workers or Remove Stored Balances before stored snapshots reflect the change (see projected time-off balances as of a future date).
Multi-Position Edge Cases and Unit Formatting
Before displaying balances to employees or managers, verify three edge cases in your tenant:
- Never Sum
HoursandDaysBlindly: In global tenants, US plans commonly trackHourswhile UK or European statutory annual leave plans trackDays. Always renderunit.descriptorright besidequantity(92.5 Hoursvs.18.5 Days). - Position-Based Plans (
Multiple Jobs): In higher education, healthcare, and hospitality tenants using position-based Time Off Plans, a worker holding two concurrent positions receives two separate entries inGET /balances—each scoped to its ownposition.idand ineligible for cross-plan balance transfers. - Manager Visibility vs. Self-Service: Under user-delegated OAuth, an employee calling
GET /balanceswith another worker’sWIDreceives403 Forbiddenor zero rows unless their security group (for example,Manageron a subordinate supervisory org) holdsWorker Data: Time Off (Time Off Balances Manager View).
Teams putting self-service balance views in front of Workday can use Kiweely Leaf (coming next) to render live, multi-unit balance cards alongside one-tap time-off booking without a Workday Extend license, or Kiweely Bridge (coming next) so employees and managers can ask for today’s balance or a future holiday projection directly inside Claude, ChatGPT, or Gemini under their own Workday OAuth permissions.
Frequently asked questions
What is the difference between GET /balances in absenceManagement v5 and WQL stored balance queries?
GET /balances in absenceManagement v5 invokes Workday's live projection engine as of the effective date parameter (factoring in future accruals, carryover caps, and pending requests), whereas WQL data sources like timeOffPlanCalculatedAndOverrideBalancesForWorker return stored snapshot and override rows.
How do you filter GET /balances to return only Time Off Plans and exclude Leave of Absence entitlements?
Pass category=7bd6531c90c100016d4b06f2b8a07ce (the Workday ID for Time Off) alongside worker={worker_wid} on GET /balances. Leave of Absence Type uses 17bd6531c90c100016d74f8dfae007d0 and Absence Table uses 17bd6531c90c100016da3f5b554007d2.
Why does an eligible Time Off Plan omit balance numbers or show zero?
Plans configured with Track Balance set to No (such as Jury Duty or Bereavement) or Accrue-As-You-Go plans with Hide Balance enabled do not maintain an accrued balance pool, even though GET /workers/{ID}/eligibleAbsenceTypes returns their Time Off Types.
Which security domains allow an employee or manager to read absence balances over REST?
Employees require Self-Service: Time Off Balances (and Self-Service: Leave of Absence Entitlements for leave balances) under the Time Off and Leave scope. Managers require Worker Data: Time Off (Time Off Balances Manager View), and HR admins use Worker Data: Time Off (Time Off Balances).