---
title: "Workday APIs: Eligible Absence Plans & Live Balances"
description: "How to query eligible Time Off Plans, unit types, and current or future balances for a worker using Workday Absence REST v5, Common REST, SOAP, and WQL."
url: https://kiweely.com/guides/workday-absence-balances-api-eligible-plans-for-worker
---

# Retrieving Eligible Absence Plans and Live Balances for a Worker via Workday APIs

Workday exposes worker absence balances across four API surfaces: GET /balances in absenceManagement v5 for real-time and future-dated balances across Time Off, Absence Tables, and Leave Types; GET /workers/{ID}/timeOffPlans in common v1; Absence\_Management SOAP; and WQL balance data sources.

-   **Checked** against Workday on November 15
-   Applies to **Workday Absence APIs & WQL**
-   4 min read
-   Published November 15
-   By Kiweely

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) |
| --- | --- | --- | --- |
|  **Absence REST (`v5`)** | `GET /balances` & `GET /workers/{ID}/eligibleAbsenceTypes` |  **Yes** (`effective=YYYY-MM-DD`) | 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`). |
|  **Common REST (`v1`)** | `GET /workers/{ID}/timeOffPlans` | Current date only | 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)`). |
|  **Absence SOAP** | `Get_Time_Off_Plan_Balances` & `Get_Absence_Inputs` | Snapshot / Period boundary | Extracting stored plan balances, manual accrual adjustments (`Put_Absence_Input`), and balance overrides (`Get_Override_Balances`). |
|  **Workday Query Language (WQL)** | `timeOffPlanCalculatedAndOverrideBalancesForWorker` & `timeOffResultsByPeriodForWorkers` | Stored / Period rows | 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`

http

```
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/json
```

A typical response returns one object per eligible plan (and per `position` when the tenant uses position-based Time Off Plans):

json

```
{
  "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`, and `Emergency 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 by `GET /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 `Bereavement` or `Jury Duty`) allow workers to request eligible Time Off Types even though no accrued balance pool exists in `GET /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:

sql

```
SELECT
  timeOffPlan,
  timeOffPlanBalanceDate,
  timeOffPlanBalanceUnits,
  unitOfTime,
  override,
  calculatedAccruals,
  comment
FROM timeOffPlanCalculatedAndOverrideBalancesForWorker(
  workerForCalculatedAndOverrideBalanceReport = '3aa5550b7fe348b98d7b5741afc6f534'
)
ORDER BY timeOffPlanBalanceDate DESC
```

And 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](https://kiweely.com/guides/workday-accrued-time-off-balance-as-of-future-date)).

## Multi-Position Edge Cases and Unit Formatting

Before displaying balances to employees or managers, verify three edge cases in your tenant:

1.  **Never Sum `Hours` and `Days` Blindly:** In global tenants, US plans commonly track `Hours` while UK or European statutory annual leave plans track `Days`. Always render `unit.descriptor` right beside `quantity` (`92.5 Hours` vs. `18.5 Days`).
2.  **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 in `GET /balances`—each scoped to its own `position.id` and ineligible for cross-plan balance transfers.
3.  **Manager Visibility vs. Self-Service:** Under user-delegated OAuth, an employee calling `GET /balances` with another worker’s `WID` receives `403 Forbidden` or zero rows unless their security group (for example, `Manager` on a subordinate supervisory org) holds `Worker Data: Time Off (Time Off Balances Manager View)`.

Teams putting self-service balance views in front of Workday can use **[Kiweely Leaf](https://kiweely.com/leaf)** (coming next) to render live, multi-unit balance cards alongside one-tap time-off booking without a Workday Extend license, or **[Kiweely Bridge](https://kiweely.com/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).

## Sources checked

-   [Setup Considerations: Absence Balances](https://doc.workday.com/admin-guide/en-us/human-capital-management/absence/time-off/time-off-plan-balances/bhu1557245686112.html)
-   [Concept: Balance Projections for Time Off](https://doc.workday.com/admin-guide/en-us/human-capital-management/absence/time-off/time-off-plan-balances/dan1370797344039.html)
-   [FAQ: Time Off Balances](https://doc.workday.com/admin-guide/en-us/human-capital-management/absence/time-off/time-off-plan-balances/tef1502717438935.html)
-   [Setup Considerations: Time Off Plans](https://doc.workday.com/admin-guide/en-us/human-capital-management/absence/time-off/set-up-time-off/fec1580088837938.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### How Workday Calculates Projected Time-Off Balances as of a Future Date Workday computes a projected time-off balance dynamically from the worker’s last stored balance date through the target future date by adding scheduled period accruals, applying carryover and upper accrual caps in sequence, and subtracting both approved and pending time-off requests.](https://kiweely.com/guides/workday-accrued-time-off-balance-as-of-future-date)
-   [### Submitting and Validating Time-Off Requests with the Workday Absence REST API Submitting time off via the Workday absenceManagement v5 REST API follows a mandatory three-step sequence: discover eligible Time Off Types, validate scheduled workdays and default daily quantities on validTimeOffDates, and POST a days array with businessProcessParameters to requestTimeOff.](https://kiweely.com/guides/workday-absence-management-rest-api-request-time-off)
-   [### Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token Send Workday SOAP requests with an HTTP Authorization Bearer header issued from a user-delegated OAuth 2.0 Authorization Code grant and leave the SOAP XML Header element empty. Workday evaluates both the API Client Functional Area scope and the signed-in worker’s Integration Permissions.](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)
-   [### Workday Time Off vs. Leave of Absence: Helping Employees Pick the Right Request Type Workday separates short-term accrued absences (Request Time Off) from extended or protected leaves (Request Leave of Absence). Time Off deducts daily units without changing worker status, whereas Leave of Absence can mark a worker On Leave, pause accruals, and require Request Return from Leave.](https://kiweely.com/guides/workday-leave-of-absence-vs-time-off-employee-request-routing)

### More guides on WQL

[All 31 guides](https://kiweely.com/guides#wql)

-   [Querying the Workday Worker Directory, Supervisory Hierarchy, and Cost Centers with WQL](https://kiweely.com/guides/workday-worker-directory-org-chart-search-fields-wql)
-   [Querying Open Job Requisitions and Supervisory Org Headcount via Workday Staffing APIs](https://kiweely.com/guides/workday-staffing-api-job-requisitions-open-positions-managers)
-   [Finding Unsubmitted Workday Time Blocks and Project Hours with WQL](https://kiweely.com/guides/workday-project-time-tracking-unsubmitted-hours-wql)
-   [Querying Pending Workday My Tasks and Inbox Approvals via API and WQL](https://kiweely.com/guides/workday-inbox-my-tasks-awaiting-action-rest-wql)
-   [Why fileLength on workerDocuments Returns 52 in WQL for Business Process Attachments](https://kiweely.com/guides/wql-workerdocuments-filelength-returns-52)
-   [Paging with POST /wql/v1/data in a PMD Grid When Queries Exceed URL Limits](https://kiweely.com/guides/wql-post-data-endpoint-grid-pagination-url-limit)
-   [Escaping Single Quotes for Multi-Value IN Clauses and Fixing Double URL-Encoded Unicode in PMD WQL](https://kiweely.com/guides/wql-pmd-single-quote-escaping-double-urlencoded-unicode)
-   [Filtering WQL Queries by Organization Hierarchy and workersByRole Without Throwing Security Errors](https://kiweely.com/guides/wql-organization-hierarchy-filter-workersbyrole)

### From the blog on WQL

[All posts](https://kiweely.com/blog)

-   [Answering Executive Span-of-Control and Headcount Questions Live from Workday](https://kiweely.com/blog/executive-org-span-of-control-attrition-questions-live-workday)
-   [Build vs. Buy a Workday MCP Server: OAuth 2.1, SOAP, WQL, and Twice-Yearly Releases](https://kiweely.com/blog/build-vs-buy-workday-mcp-server-engineering-cost)
-   [What happens after ChatGPT writes your WQL query](https://kiweely.com/blog/after-chatgpt-writes-your-wql)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
