Plans, Enrollment & Elections

Configure plans, capture elections, and manage enrollment lifecycle. Plans, Elections & Enrollments allow developers to define available benefit offerings, capture participant selections, and manage enrollment records over time. It represents the full lifecycle of benefits administration: from plan configuration to user enrollment and ongoing updates. Use this resource to set up plan structures, support open enrollment and life event changes, and maintain accurate records of participant elections and active enrollments across benefit programs.

Core Administration Services

Plan Years API

The Plan Years API establishes the foundational temporal cycles for all benefit offerings. It defines the specific periods for active coverage, contribution collection, and claim incurrence.

• Lifecycle Management: Transition benefit cycles through Upcoming, Active, and Closed states.

• Temporal Boundaries: Configure three distinct sub-periods: the Active Period for coverage, the Enrollment Window for user elections, and Run-out/Grace Periods for late claim submissions.

• Actionable Discovery: Utilize high-level filtering (for example, relevance=ACTIONABLE) to identify years currently requiring administrative or user attention.

Plans API

The Plans API defines the actual financial or healthcare products (for example, HSA, Medical FSA, Commuter) offered to consumers within a specific plan year.

• Granular Rule Engine: Configure over 50 parameters, including contribution caps, reimbursement types, and medical enrollment prerequisites.

• Financial Tiering: Support complex employer contribution schedules based on coverage tiers, such as Individual vs. Family.

• Merchant Controls: Restrict debit card usage to specific networks (for example, Pharmacies) through merchant category network configurations.

Elections API

The Elections API manages specific consumer choices, representing the financial commitments and coverage levels selected for a benefit period.

• Contribution Transparency: Access detailed annual totals and calculated per-pay-period deduction amounts to ensure payroll accuracy.

• Flexible Querying: Pivot election data by enrollment event, plan year, or specific benefit plan to verify participant choices.

• Status Monitoring: Track whether a selection is Active, Pending, or Historical to maintain accurate benefit representation.

Enrollments API

The Enrollments API serves as the definitive record of a consumer’s actual participation in benefit plans over time.

• Coverage Tracking: Monitor the entire state of benefits from initial enrollment through termination, including effective start and end dates.

• Flexible Identification: Query portfolios using multiple identifier types, including Person ID, Employee Number, or Employer-specific IDs.

• Eligibility Verification: Confirm active coverage before authorizing transactions or secondary plan enrollments.

Integration Standards

Scopes & Permissions

Access to these services is governed by specific OAuth scopes:

Data Integrity & Safety

Idempotency: All POSToperations require a unique Idempotency-Key (UUID v4) to prevent duplicate record creation during network retries. Optimistic Locking: Update operations (PUT) utilize version control (ETags or version integers) to prevent concurrent update conflicts. Standardized Formats: All identifiers must be UUID v4. Timestamps and dates must follow ISO 8601 standards (for example, YYYY-MM-DDTHH:MM:SSZ).

Global Error Reference