---
title: "Read Workday Benefits Elections & Dependents via APIs"
description: "How Workday Benefits WQL data sources, RaaS reports, SOAP operations, and Self-Service Benefits domains expose active elections and dependents safely."
url: https://kiweely.com/guides/workday-view-benefits-elections-dependents-beneficiaries-api
---

# Reading Current Benefits Elections and Dependents Through Workday Self-Service APIs

Workday exposes a worker’s active benefit plan elections, coverage targets, employee per-period costs, and enrolled dependents through WQL data sources (allCurrentBenefitElections, processingWorkerDependents), RaaS reports, and Human\_Resources SOAP—governed by Self-Service: Benefits domains.

-   **Checked** against Workday on November 15
-   Applies to **Workday Benefits**
-   5 min read
-   Published November 15
-   By Kiweely

To read an authenticated worker’s current medical, dental, vision, spending account, insurance, and retirement elections alongside their covered dependents and beneficiaries, use **WQL** (`allCurrentBenefitElections` and `processingWorkerDependents`) or an **employee-scoped RaaS report** secured to the `Self-Service: Benefits`, `Self-Service: Dependents`, and `Self-Service: Beneficiaries` domains in the **Benefits** functional area. When calling from a SOAP integration, use `Get_Workers` in the `Human_Resources` service with `Include_Benefit_Enrollments` enabled in `Response_Group`.

Developers coming from REST-only HR platforms often search Workday’s REST catalog expecting a `/workers/{ID}/benefitElections` endpoint, find only specialized `benefitEnrollmentEventOfferings` or `benefitPartner` specs, and mistakenly fall back to privileged administrative reports. Choosing the right self-service data source and security domain avoids over-privileged credentials and historical-row bugs.

## Comparing Workday’s Three Read Paths for Benefits & Dependents

| Read Path | Primary Data Source / Operation | Best Use Case | Key Pitfall to Avoid |
| --- | --- | --- | --- |
|  **Workday Query Language (WQL)** | `allCurrentBenefitElections`, `processingWorker`, `processingWorkerDependents` via `/wql/v1/data` | Live employee portals and assistants reading current plans, employee/employer costs, and active dependents in JSON. | Querying `allBenefitElections` instead of `allCurrentBenefitElections` pulls every historical life event and degrades performance. |
|  **Reports as a Service (RaaS)** | Custom report on `processingWorker` or `allCurrentBenefitElections` (`format=json`) | Curated self-service payloads that combine plan name, coverage target, group number, dependent names, and beneficiary percentages while omitting national IDs. | Building the report on an admin-only data source instead of a self-service-compatible source breaks `Employee As Self` OAuth calls. |
|  **SOAP Web Services** | `Human_Resources` -> `Get_Workers` (`Include_Benefit_Enrollments = true`) & `Benefits_Administration` -> `Get_Benefit_Plans` | Enterprise carrier or downstream system integrations requiring deeply nested `Benefit_Enrollment_Data`, `Dependent_Coverage_Data`, and `Beneficiary_Designation_Data` XML. | Omitting `<wd:Exclude_Personal_Information>false</wd:Exclude_Personal_Information>` or leaving `Include_Benefit_Enrollments` at its default `false` returns an empty benefits block. |

> **Critical Warning on Write Web Services:** Never wire a self-service application to `Change_Benefits` or `Bulk_Import_Change_Benefits` in `Benefits_Administration` for incremental single-plan edits. Those SOAP operations are designed for initial legacy conversions and acquisitions: they **waive all existing worker elections matching the specified `Benefit_Event_Type`**, replace them wholesale with the payload, bypass Business Process step routing on `Change Benefits for Life Event`, and do not participate in Coordination of Events unless configured separately. For retirement-only updates, Workday provides `Enroll_in_Retirement_Savings_Plans`.

## Required Security Domains in the Benefits Functional Area

When an application authenticates as the worker via OAuth 2.0 Authorization Code Grant (`Register API Client` with the **Benefits** Functional Area scope), Workday evaluates these Employee Self-Service (ESS) domain security policies for `Employee As Self`:

-   **`Self-Service: Benefits`** (`Benefits` functional area): Controls viewing current benefit elections, expanded plan details, and benefits as of a specified date.
-   **`Self-Service: Dependents`** (`Benefits` functional area): Controls viewing and maintaining dependent records on the worker’s profile.
-   **`Self-Service: Beneficiaries`** and **`Self-Service Add Beneficiaries in Benefits Enrollment`** (`Benefits` functional area): Controls viewing beneficiary designations and allocations (including individual persons and legal trusts).
-   **`Self-Service: Benefits and Pay Hub`** and **`Self-Service: Insurance Calculated Coverage`** (`Core Compensation` / `Benefits`): Controls hub cards and calculated salary-multiple insurance coverage amounts.

Note two built-in Workday privacy behaviors when testing as an employee versus a Benefits Partner (`Worker Data: Beneficiaries and Dependents`):

1.  **Inactive Dependents Hidden from Workers:** If a dependent previously had coverage and was inactivated (`Dependent -> Inactivate`), Workday hides that record from the worker’s self-service view while still displaying `(Inactive)` to Benefits Partners and Administrators.
2.  **Country Localization Hiding:** If an administrator hides dependent attributes (`Tobacco Use`, `Full-time Student`, or `Disabled`) per country on the **Maintain Localization Settings** task, Workday suppresses those fields across self-service views and enrollment events automatically.

## Reading Current Elections and Costs with WQL

### 1\. Querying Active Benefit Elections (`allCurrentBenefitElections`)

`allCurrentBenefitElections` uses `Benefit Election` as its primary business object and returns all currently enrolled elections as of the report effective date (supporting an explicit effective date when checking upcoming plan-year elections after Open Enrollment finalization):

sql

```
SELECT worker,
       benefitType,
       benefitPlan,
       benefitProvider,
       coverage,
       groupNumber,
       electionStatusDescription,
       elected,
       waived,
       currentElectionCoverageBeginDate,
       coverageEndDate,
       employeeCostPerBenefitGroupFrequencyPre_Tax,
       employeeCostPerBenefitGroupFrequencyPost_Tax,
       employerContributionPerBenefitGroupFrequency,
       dependents,
       beneficiaries_People
FROM allCurrentBenefitElections
WHERE elected = true
```

Key field distinctions on `allCurrentBenefitElections`:

-   **Pre-Tax vs. Post-Tax Cost:** `employeeCostPerBenefitGroupFrequencyPre_Tax` and `employeeCostPerBenefitGroupFrequencyPost_Tax` reflect the per-pay-period deduction frequency of the worker’s **Benefit Group** (for example, Biweekly), whereas `employeeCostPerBenefitPlanFrequency` reflects the plan’s native rate frequency (often Monthly). Displaying the Plan Frequency rate when an employee asks about their paycheck deduction causes an immediate mismatch.
-   **Coverage Begin Dates:** `currentElectionCoverageBeginDate` shows when the active election started (such as January 1 of the current plan year), whereas `coverageBeginDateForBenefitPlan` reflects continuous enrollment start in that plan.
-   **Waived Plans:** Filtering `WHERE elected = true` excludes coverage types the employee explicitly waived (`waived = true`), while dropping that filter lets you confirm both elected and waived coverage lines.

### 2\. Querying the Authenticated Worker’s Dependents (`processingWorkerDependents`)

To list all active dependents belonging solely to the authenticated processing worker without passing a worker ID filter, query `processingWorkerDependents` (or traverse the `dependents{...}` Related Business Object from `processingWorker`):

sql

```
SELECT relationship,
       full_TimeStudent,
       disabled,
       primaryAddress_City,
       primaryAddress_StateProvince,
       primaryAddress_CountryName
FROM processingWorkerDependents
```

Or pull grouped election categories and dependent names directly from `processingWorker` using WQL Related Business Object `{}` notation:

sql

```
SELECT worker,
       benefitGroup,
       benefitsServiceDate,
       healthCareElections,
       healthSavingsAccountElections,
       spendingAccountElections,
       insuranceElections,
       retirementSavingsElections,
       dependents{legalName_FirstName, legalName_LastName, relationship},
       beneficiaries_People
FROM processingWorker
```

## Reading Detailed Enrollment XML via `Get_Workers` SOAP

When an integration needs carrier-grade detail—such as `Original_Coverage_Begin_Date_for_Benefit_Coverage_Type`, `Dependent_Coverage_Data` per plan, or `Beneficiary_Allocation_Data` primary/contingent percentages—call `Get_Workers` in the `Human_Resources` SOAP service with `Include_Benefit_Enrollments` set to `true` and every unrelated response group explicitly turned off to keep response payloads small:

xml

```
<wd:Get_Workers_Request xmlns:wd="urn:com.workday/bsvc" wd:version="v45.1">
  <wd:Request_References>
    <wd:Worker_Reference>
      <wd:ID wd:type="Employee_ID">21004</wd:ID>
    </wd:Worker_Reference>
  </wd:Request_References>
  <wd:Response_Filter>
    <wd:As_Of_Effective_Date>2026-11-15</wd:As_Of_Effective_Date>
  </wd:Response_Filter>
  <wd:Response_Group>
    <wd:Include_Reference>true</wd:Include_Reference>
    <wd:Include_Personal_Information>false</wd:Include_Personal_Information>
    <wd:Include_Employment_Information>false</wd:Include_Employment_Information>
    <wd:Include_Compensation>false</wd:Include_Compensation>
    <wd:Include_Organizations>false</wd:Include_Organizations>
    <wd:Include_Benefit_Enrollments>true</wd:Include_Benefit_Enrollments>
  </wd:Response_Group>
</wd:Get_Workers_Request>
```

Setting `As_Of_Effective_Date` to January 1 of the upcoming plan year (after Open Enrollment events have been finalized via `Finalize Open Benefit Event Elections`) lets a self-service view show employees both their **Current Year** and **Next Year** elections side by side.

## Data Minimization Checklist Before Exposing Benefits APIs

1.  **Never Expose Dependent National IDs:** Dependent records in Workday store Social Security Numbers / National IDs required for ACA `1095-C` reporting. Exclude SSN/National ID fields from every RaaS report, WQL `SELECT` list, and memory redaction policy.
2.  **Use `Benefit Group Frequency` for Paycheck Cost Displays:** Match the cost column to the worker’s pay group frequency so employees see the exact pre-tax and post-tax figure that matches their payslip.
3.  **Check Unfinalized Open Enrollment State:** During active Open Enrollment (`Initiated` / `Submitted` prior to finalization), distinguish in-progress enrollment event elections from finalized `allCurrentBenefitElections` rows so workers know whether a draft election still needs submission.

Whether employees ask [Kiweely Bridge](https://kiweely.com/bridge) (coming next) *“Is my spouse covered on my vision plan and what is my biweekly pre-tax cost?”* or open a unified Pay, Time Off, and Benefits portal built with [Kiweely Leaf](https://kiweely.com/leaf) (coming next), both products execute these exact self-service reads live under the signed-in employee’s own Workday OAuth grant with zero HR or dependent records stored at rest.

## Frequently asked questions

### Why should I query allCurrentBenefitElections instead of allBenefitElections in WQL?

Workday explicitly recommends allCurrentBenefitElections over allBenefitElections because allBenefitElections scans historical election rows across every past enrollment event, causing slow query execution and returning superseded rows unless carefully filtered.

### Why do inactive dependents show up for Benefits Partners but not for employees in Self-Service?

In Workday, workers can view only active dependents and beneficiaries, whereas Benefits Partners and Administrators on Worker Data: Beneficiaries and Dependents see inactive records with (Inactive) appended to the name.

### Why isn't there a single GET /workers/{ID}/benefitElections REST endpoint in standard Workday REST?

Workday's public REST catalog focuses Benefits endpoints on enrollment event offerings and partner integrations rather than full worker election summaries, making WQL, employee-scoped RaaS reports, or Get\_Workers SOAP (Include\_Benefit\_Enrollments) the standard read paths.

### Should self-service apps use the Change Benefits SOAP web service to update one benefit plan?

No. Workday documents that Change Benefits and Bulk Import Change Benefits are mass-conversion web services that waive and overwrite all elections matching the specified Benefit Event Type, ignoring coordinated events and additional workflow steps.

## Sources checked

-   [Workday Manage Dependents and Beneficiaries](https://doc.workday.com/admin-guide/en-us/human-capital-management/benefits/dependents-and-beneficiaries/kur1411759334568.html)
-   [Workday Reference: Benefits and Pay Hub](https://doc.workday.com/admin-guide/en-us/human-capital-management/compensation/manage-compensation/mtl1658352925946.html)
-   [Workday Steps: Set Up Employee Self-Service](https://doc.workday.com/admin-guide/en-us/human-capital-management/employee-and-manager-self-service/dan1370797596840.html)
-   [Workday Concept: Change Benefits Web Services](https://doc.workday.com/admin-guide/en-us/human-capital-management/benefits/benefit-changes/gxz1676332347728.html)

## Related guides

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

-   [### How to Authenticate Workday Studio and External Tools Using an OAuth API Client with PKCE (When SSO Blocks Passwords) When SSO leaves consultants without a Workday password, register an API Client with Authorization Code Grant and Support Proof Key for Code Exchange enabled, then use that client ID with Studio or Vine OAuth sign-in instead of username and password auth.](https://kiweely.com/guides/workday-api-client-pkce-sso-without-workday-password)
-   [### Why is a worker’s Workday Open Enrollment On Hold or missing after a backdated change? A backdated life event or staffing change triggers Coordination of Events, which puts the later Open Enrollment event On Hold until the earlier event completes, then rescinds and recreates it. Finish or cancel the earlier event in Benefit Election History.](https://kiweely.com/guides/workday-open-enrollment-stuck-disappeared-elections)
-   [### How Future-Dated Dependents and ‘View Dependent As Of’ Work in Workday Benefits Workday tracks dependent relationships and eligibility attributes as effective-dated records, isolating upcoming additions in the Future Dependents grid and evaluating historical or upcoming states via View Dependent As Of. Correct wrong initiation dates with Revise Dependent Event.](https://kiweely.com/guides/workday-dependent-effective-dating-future-dependents)
-   [### Should I use RaaS, WQL or the REST API to extract data from Workday? Use RaaS for a saved report’s output, WQL for a filtered, grouped or paged extract of up to 1 million rows, and REST for small, low-latency reads of one resource. Limits and sources are in the table.](https://kiweely.com/guides/workday-raas-wql-rest)

### More guides on Integrations and APIs

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

-   [Auditing External API Calls in Workday Sign-On History and Activity Logs](https://kiweely.com/guides/workday-view-api-client-audit-logs-sign-on-history)
-   [Entering Time Blocks and Check-In/Check-Out Events via Workday Time Tracking APIs](https://kiweely.com/guides/workday-time-tracking-api-clock-in-out-enter-time)
-   [Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)
-   [Diagnosing Workday REST API 403 Forbidden: Missing Client Scope vs. Worker Domain Security](https://kiweely.com/guides/workday-rest-api-403-forbidden-user-security-vs-client-scope)
-   [Workday Expenses REST API: create a Quick Expense, upload a receipt and submit an Expense Report](https://kiweely.com/guides/workday-expenses-rest-api-receipt-attachments-expense-lines)
-   [Designing for Workday Tenant API Concurrency and Rate Limits During Peak Employee Traffic](https://kiweely.com/guides/workday-api-rate-limits-concurrency-workforce-self-service)
-   [Calling Workday RaaS Reports with User-Delegated OAuth Instead of an ISU](https://kiweely.com/guides/workday-raas-user-delegated-oauth-vs-isu-basic-auth)
-   [Updating Preferred Name, Pronouns, and Contact Information via the Workday Person API](https://kiweely.com/guides/workday-person-api-legal-preferred-name-contact-updates)

### From the blog on Integrations and APIs

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

-   [How Workday’s Twice-Yearly Releases Break In-House MCP Servers and REST Integrations](https://kiweely.com/blog/how-workday-twice-yearly-releases-break-custom-mcp-servers)
-   [Turning Your Existing Workday RaaS Reports into Governed AI Tools](https://kiweely.com/blog/exposing-existing-workday-raas-reports-to-claude-and-chatgpt)
-   [Embedding Live Workday Time Off, Pay, and Approvals Inside DingTalk, Feishu, and Lark](https://kiweely.com/blog/embedding-workday-self-service-inside-dingtalk-feishu-lark)

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