Plans

Overview

The Plans API is the architectural core of the benefit system. While a Plan Year defines the temporal boundaries, a Plan defines the actual financial or healthcare product (e.g., Medical FSA, HSA, Commuter) offered to a consumer. This suite of endpoints allows administrators to manage the full lifecycle of a plan—from complex business rule configuration and contribution logic to real-time updates and portfolio auditing.

Key Features

• Granular Rule Engine: Configure over 50 parameters including contribution caps, reimbursement types, and enrollment prerequisites.
• Identity-Based Scoping: Retrieve plan catalogs for specific consumers or entire employer groups.
• Safety & Integrity: Robust protection against duplicate entries (Idempotency) and concurrent update conflicts (Optimistic Locking).
• Financial Tiering: Support for complex employer contribution schedules based on coverage tiers (Individual vs. Family).

Scopes & Permissions

Endpoint Summary

List Plans

GET /plans

Retrieves a paginated list of plans.

• Constraint: Requires plan_year_id and at least one of consumer_id or employer_id.
• Filtering: Supports filtering by plan_type (for example, HSA, DENTAL).

Get Plan (by ID)

GET /plans/{plan_id}

Retrieves the full configuration object for a specific plan.

• Use Case: Loading detailed plan rules, descriptions, or status for a single resource.

Create Plan

POST /plans

Creates a new benefit plan with exhaustive business logic.

• Requirement: A unique Idempotency-Key (UUID v4) in the header.
• Key Fields: plan_template_id, maximum_total_contribution, extension_date, and is_pre_tax.

Update Plan

PUT /plans/{plan_id}

Performs a full replacement of an existing plan’s core properties.

• Requirement: Must provide the current version integer for optimistic locking.
• Key Fields: display_name, merchant_category_network, and version.

Core Concepts

Contribution & Limit Management

The Create Plan endpoint allows for high-fidelity financial setup:

• Employee Limits: Defined by maximum_total_contribution and maximum_monthly_contribution.
• Employer Match: Can be tiered by coverage (for example, family_employer_contribution vs individual_employer_contribution).
• Prerequisites: require_medical_enrollment ensures a consumer has core coverage before enrolling in secondary plans.

Claim & Spend Rules

Plans dictate how and where funds can be used:

• Run-out Windows: file_claims_day_count determines how long after a plan year ends a user can still submit claims.
• Merchant Controls: merchant_category_network restricts debit card swipes to specific business types (for example, Pharmacies).

Data Integrity

• Idempotency: Used in POSTto ensure that network retries do not create duplicate plans.
• Optimistic Locking: Used in PUTvia the version field. If the version you submit is older than the version on the server, the update is rejected with a 412 Precondition Failed.

Error Handling