Elections

Overview

The Elections API manages consumer benefit choices, representing the specific financial commitments or coverage levels a consumer has selected for a benefit period. These endpoints allow developers to retrieve election records to verify contribution amounts, effective dates, and statuses across various plans and enrollment cycles.

Key Features

Flexible Querying: Pivot election data by enrollment event, plan year, or specific benefit plan.

Contribution Transparency: Access detailed breakdowns of annual totals and per-pay-period deduction amounts.

Status Tracking: Monitor whether an election is active, pending, or historical to ensure accurate benefit representation.

Use Cases

Coverage Summaries: Displaying a user’s chosen annual HSA or FSA contribution in a member portal.

Payroll Accuracy: Fetching current election amounts to ensure payroll systems deduct the correct amounts.

Enrollment History: Reviewing a consumer’s past elections to assist in year-over-year benefit planning.

Scopes & Permissions

Core Concepts

Search Constraints (List Endpoint)

To ensure performance and security, the List Elections endpoint requires the consumer_id plus at least one of the following filters:

• enrollment_id: Scopes elections to a specific enrollment event (for example, Open Enrollment 2026).
• plan_id: Scopes results to a specific benefit type (for example, Medical FSA).
• plan_year_id: Scopes results to a specific calendar or fiscal benefit cycle.

Resource Model

An Election object represents the finalized choice. Key attributes typically include:

• annual_amount: The total dollar amount elected for the year.
• pay_period_amount: The calculated deduction per payroll cycle.
• status: Indicates if the election is Active, Pending, or Historical.

Pagination

The list endpoint utilizes zero-based pagination to manage election history.

Error Handling

Idempotency

Both endpoints in this section use the GET method. They are idempotent and safe, meaning they do not modify any election records or server states and can be called repeatedly with the same result.