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 |
|---|---|---|---|
| Read PathWorkday Query Language (WQL) | Primary Data Source / OperationallCurrentBenefitElections, processingWorker, processingWorkerDependents via /wql/v1/data |
Best Use CaseLive employee portals and assistants reading current plans, employee/employer costs, and active dependents in JSON. | Key Pitfall to AvoidQuerying allBenefitElections instead of allCurrentBenefitElections pulls every historical life event and degrades performance. |
| Read PathReports as a Service (RaaS) | Primary Data Source / OperationCustom report on processingWorker or allCurrentBenefitElections (format=json) |
Best Use CaseCurated self-service payloads that combine plan name, coverage target, group number, dependent names, and beneficiary percentages while omitting national IDs. | Key Pitfall to AvoidBuilding the report on an admin-only data source instead of a self-service-compatible source breaks Employee As Self OAuth calls. |
| Read PathSOAP Web Services | Primary Data Source / OperationHuman_Resources -> Get_Workers (Include_Benefit_Enrollments = true) & Benefits_Administration -> Get_Benefit_Plans |
Best Use CaseEnterprise carrier or downstream system integrations requiring deeply nested Benefit_Enrollment_Data, Dependent_Coverage_Data, and Beneficiary_Designation_Data XML. |
Key Pitfall to AvoidOmitting <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_BenefitsorBulk_Import_Change_BenefitsinBenefits_Administrationfor incremental single-plan edits. Those SOAP operations are designed for initial legacy conversions and acquisitions: they waive all existing worker elections matching the specifiedBenefit_Event_Type, replace them wholesale with the payload, bypass Business Process step routing onChange Benefits for Life Event, and do not participate in Coordination of Events unless configured separately. For retirement-only updates, Workday providesEnroll_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(Benefitsfunctional area): Controls viewing current benefit elections, expanded plan details, and benefits as of a specified date.Self-Service: Dependents(Benefitsfunctional area): Controls viewing and maintaining dependent records on the worker’s profile.Self-Service: BeneficiariesandSelf-Service Add Beneficiaries in Benefits Enrollment(Benefitsfunctional area): Controls viewing beneficiary designations and allocations (including individual persons and legal trusts).Self-Service: Benefits and Pay HubandSelf-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):
- 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. - Country Localization Hiding: If an administrator hides dependent attributes (
Tobacco Use,Full-time Student, orDisabled) 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):
SELECT worker,
benefitType,
benefitPlan,
benefitProvider,
coverage,
groupNumber,
electionStatusDescription,
elected,
waived,
currentElectionCoverageBeginDate,
coverageEndDate,
employeeCostPerBenefitGroupFrequencyPre_Tax,
employeeCostPerBenefitGroupFrequencyPost_Tax,
employerContributionPerBenefitGroupFrequency,
dependents,
beneficiaries_People
FROM allCurrentBenefitElections
WHERE elected = trueKey field distinctions on allCurrentBenefitElections:
- Pre-Tax vs. Post-Tax Cost:
employeeCostPerBenefitGroupFrequencyPre_TaxandemployeeCostPerBenefitGroupFrequencyPost_Taxreflect the per-pay-period deduction frequency of the worker’s Benefit Group (for example, Biweekly), whereasemployeeCostPerBenefitPlanFrequencyreflects 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:
currentElectionCoverageBeginDateshows when the active election started (such as January 1 of the current plan year), whereascoverageBeginDateForBenefitPlanreflects continuous enrollment start in that plan. - Waived Plans: Filtering
WHERE elected = trueexcludes 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):
SELECT relationship,
full_TimeStudent,
disabled,
primaryAddress_City,
primaryAddress_StateProvince,
primaryAddress_CountryName
FROM processingWorkerDependentsOr pull grouped election categories and dependent names directly from processingWorker using WQL Related Business Object {} notation:
SELECT worker,
benefitGroup,
benefitsServiceDate,
healthCareElections,
healthSavingsAccountElections,
spendingAccountElections,
insuranceElections,
retirementSavingsElections,
dependents{legalName_FirstName, legalName_LastName, relationship},
beneficiaries_People
FROM processingWorkerReading 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:
<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
- Never Expose Dependent National IDs: Dependent records in Workday store Social Security Numbers / National IDs required for ACA
1095-Creporting. Exclude SSN/National ID fields from every RaaS report, WQLSELECTlist, and memory redaction policy. - Use
Benefit Group Frequencyfor 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. - Check Unfinalized Open Enrollment State: During active Open Enrollment (
Initiated/Submittedprior to finalization), distinguish in-progress enrollment event elections from finalizedallCurrentBenefitElectionsrows so workers know whether a draft election still needs submission.
Whether employees ask Kiweely 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 (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.