Skip to content
KiweelyKiweelyKiweely

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
  • Applies to Workday Benefits
  • 5 min read
  • Published
  • By Kiweely
On this page

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_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 (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.

Sources checked

Related guides

All guides

Let Workday check the work.

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

Get the next guide in your inbox.

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

We’ll email you once to confirm. Unsubscribe in one click from any issue.