Plan Years

Overview

The Plan Years API suite defines the foundational temporal cycles for all benefit offerings. A Plan Year represents the specific period (usually 12 months) during which coverage is active, contributions are collected, and claims are incurred. These endpoints allow administrators to manage the entire lifecycle of a benefit year—from initial creation and enrollment window configuration to historical auditing and status tracking.

Key Features

• Lifecycle Management: Move plan years through Upcoming, Active, and Closed states.
• Enrollment Control: Define precise windows for when consumers or employers can interact with benefit elections.
• Actionable Relevance: High-level filtering to identify years currently in “Run-out” or “Grace” periods.
• Concurrency Protection: Integrated optimistic locking (ETags) and idempotency keys to ensure data integrity during updates and creation.

Scopes & Permissions

Endpoint Summary

List Plan Years

GET /plan-years

Retrieves a paginated list of benefit cycles.

• Key Query Params: relevance=ACTIONABLE (finds active/upcoming years), inactive_plan_year_limit (controls historical depth), and status.
• Constraint: Must provide either consumer_id or employer_id.

Get Plan Year (by ID)

GET /plan-years/{plan_year_id}

Retrieves full details for a specific record.

• Key Attributes: Returns critical deadlines including run_out_date and grace_period_end_date.

Create Plan Year

POST /plan-years

Initializes a new benefit cycle for an employer.

• Requirement: Must include a unique Idempotency-Key in the header to prevent duplicate creation.
• Key Body Fields: name, start_date, status, and employer_id.

Update Plan Year

PUT /plan-years/{plan_year_id}

Replaces properties for an existing record.

• Requirement: Must include an If-Match header (ETag) for optimistic locking.
• Key Body Fields: enroll_start_date, enroll_end_date, allow_ptp_claims, and display_name.

Core Concepts

Temporal Boundaries

A Plan Year configuration is defined by three distinct “sub-periods”:

• Active Period: Defined by valid_start_date and valid_end_date. This is when the insurance/benefit is actually in effect.
• Enrollment Window: Defined by enroll_start_date and enroll_end_date. This is the only time users can make elections.
• Run-out/Grace Period: Calculated dates that allow users to submit claims for a “Closed” year.

Safety Mechanisms

• Optimistic Locking: The PUToperation requires an ETag. If the record was modified by another process since you last read it, the update will fail with a 412 Precondition Failed to prevent data overwrites.
• Idempotency: The POSToperation uses a client-generated UUID to ensure that retrying a creation request (due to a timeout) doesn’t result in two identical plan years.

Error Handling