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:
| Scope | Description | Required For |
| read:planyears | View plan year configurations and deadlines | GET operations |
| write:planyears | Create or modify benefit cycles | POST, PUT operations |
| read:plans | View benefit catalogs and granular rules | GET operations |
| write:plans | Configure new benefit offerings or update logic | POST, PUT operations |
| read:enrollments | Access consumer participation records | GET operations |
| read:elections | Access consumer contribution and selection data | GET operations |
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
| Status Code | Meaning | Common Causes |
| 400 | Bad Request | Missing required identifiers or invalid date-time logic (for example, end date before start date). |
| 409 | Conflict | Duplicate idempotency key or overlapping plan year configurations for the same employer. |
| 412 | Precondition Failed | The provided version or ETag is outdated, indicating a concurrent modification. |
| 404 | Not Found | The specified plan_id, plan_year_id, enrollment_id, or election_id does not exist. |
Endpoints
v1/elections?enrollment_id=enrollment_id&plan_id=plan_id&plan_year_id=plan_year_id&consume...
v1/elections/{election_id}?enrollment_id=enrollment_id
v1/enrollments?consumer_id=consumer_id&consumer_identifier_type=consumer_identifier_type&e...
v1/enrollments/{enrollment_id}
v1/plan-years?consumer_id=consumer_id&employer_id=employer_id&year=year&status=status&rele...
v1/plan-years/{plan_year_id}
v1/plan-years
v1/plan-years/{plan_year_id}
v1/plans?plan_year_id=plan_year_id&consumer_id=consumer_id&employer_id=employer_id&plan_ty...
v1/plans/{plan_id}
v1/plans
v1/plans/{plan_id}