Skip to content
Vitable Docs Vitable Docs Vitable Docs
Get started
API Reference
Plan Years

Get plan year details

plan_years.retrieve(strplan_year_id) -> PlanYear
get/v1/plan-years/{plan_year_id}

Retrieves detailed configuration for a specific plan year by ID. Returns coverage dates, open enrollment period, available plans, and contribution structure.

ParametersExpand Collapse
plan_year_id: str
ReturnsExpand Collapse
class PlanYear: …

Serializer for Plan Year entity in public API responses.

A Plan Year represents a benefit period configuration including coverage dates, open enrollment windows, available plans, and contribution structures.

id: str

Unique plan year identifier with 'plyr_' prefix

benefit_product_id: str

ID of the benefit product (bprd_*)

contribution_classes: List[ContributionClass]

List of contribution classes defining eligibility tiers and cost structures

id: str

Unique contribution class identifier

employee_contribution_cents: int

Employee's monthly contribution amount in cents

employer_contribution_cents: int

Employer's monthly contribution amount in cents

employment: str

Employment type for this contribution class (e.g., 'full_time', 'part_time')

family_status: CoverageTier
  • Unspecified - Unspecified
  • EE - Ee
  • ES - Es
  • EC - Ec
  • EF - Ef
Accepts one of the following:
"Unspecified"
"EE"
"ES"
"EC"
"EF"
coverage_end: date

Date when benefit coverage ends

formatdate
coverage_start: date

Date when benefit coverage begins

formatdate
created_at: datetime

Timestamp when the plan year was created

formatdate-time
employer_id: str

ID of the employer this plan year is for (empr_*)

open_enrollment_end_date: date

Date when open enrollment period ends

formatdate
open_enrollment_start_date: date

Date when open enrollment period begins

formatdate
plans: List[Plan]

List of insurance plans available in this plan year

id: str

Unique plan identifier with 'plan_' prefix

carrier_plan_id: str

Reference to the carrier's plan definition (cplan_*)

monthly_premium_cents: int

Base monthly premium in cents

name: str

Display name of the insurance plan

deductible_cents: Optional[int]

Annual deductible amount in cents

out_of_pocket_max_cents: Optional[int]

Annual out-of-pocket maximum in cents

tier: Optional[PlanTier]
  • Bronze - Bronze
  • Silver - Silver
  • Gold - Gold
  • Platinum - Platinum
Accepts one of the following:
"Bronze"
"Silver"
"Gold"
"Platinum"
status: PlanYearStatus
  • draft - Draft
  • open_enrollment - Open Enrollment
  • active - Active
  • expired - Expired
Accepts one of the following:
"draft"
"open_enrollment"
"active"
"expired"
updated_at: datetime

Timestamp when the plan year was last updated

formatdate-time
Get plan year details
from vitable_connect_api import VitableConnectAPI

client = VitableConnectAPI(
    api_key="My API Key",
)
plan_year = client.plan_years.retrieve(
    "plyr_abc123def456",
)
print(plan_year.id)
{
  "id": "id",
  "benefit_product_id": "benefit_product_id",
  "contribution_classes": [
    {
      "id": "id",
      "employee_contribution_cents": 0,
      "employer_contribution_cents": 0,
      "employment": "employment",
      "family_status": "Unspecified"
    }
  ],
  "coverage_end": "2019-12-27",
  "coverage_start": "2019-12-27",
  "created_at": "2019-12-27T18:11:19.117Z",
  "employer_id": "employer_id",
  "open_enrollment_end_date": "2019-12-27",
  "open_enrollment_start_date": "2019-12-27",
  "plans": [
    {
      "id": "id",
      "carrier_plan_id": "carrier_plan_id",
      "monthly_premium_cents": 0,
      "name": "name",
      "deductible_cents": 0,
      "out_of_pocket_max_cents": 0,
      "tier": "Bronze"
    }
  ],
  "status": "draft",
  "updated_at": "2019-12-27T18:11:19.117Z"
}
Returns Examples
{
  "id": "id",
  "benefit_product_id": "benefit_product_id",
  "contribution_classes": [
    {
      "id": "id",
      "employee_contribution_cents": 0,
      "employer_contribution_cents": 0,
      "employment": "employment",
      "family_status": "Unspecified"
    }
  ],
  "coverage_end": "2019-12-27",
  "coverage_start": "2019-12-27",
  "created_at": "2019-12-27T18:11:19.117Z",
  "employer_id": "employer_id",
  "open_enrollment_end_date": "2019-12-27",
  "open_enrollment_start_date": "2019-12-27",
  "plans": [
    {
      "id": "id",
      "carrier_plan_id": "carrier_plan_id",
      "monthly_premium_cents": 0,
      "name": "name",
      "deductible_cents": 0,
      "out_of_pocket_max_cents": 0,
      "tier": "Bronze"
    }
  ],
  "status": "draft",
  "updated_at": "2019-12-27T18:11:19.117Z"
}