Skip to content
Vitable Docs Vitable Docs Vitable Docs
API Reference
Employers

Get one of an employer's benefit plan years

employers.retrieve_benefit_plan_year(strbenefit_plan_year_id, EmployerRetrieveBenefitPlanYearParams**kwargs) -> EmployerRetrieveBenefitPlanYearResponse
GET/v1/employers/{employer_id}/benefit-plan-years/{benefit_plan_year_id}

Returns one benefit plan year in full — its benefit details plus the per-benefit enrollment rate and SPD link — addressed by its benefit_plan_year_id. The caller must be authorized for the employer; an unknown or unauthorized plan year returns 404.

ParametersExpand Collapse
employer_id: str

Unique employer identifier (empr_*)

benefit_plan_year_id: str

Unique benefit-plan-year identifier (plyr_*).

ReturnsExpand Collapse
class EmployerRetrieveBenefitPlanYearResponse: …

Response containing a single employer benefit plan year resource.

data: Data

One plan year, detail view.

Standalone (no shared base) so the exact detail payload is readable in one place; the list serializer is a separate class even where fields overlap. Detail carries the SPD link and omits the list-only is_current flag.

benefit_id: str

Prefixed benefit identifier (bprd_*).

benefit_plan_year_id: str

Prefixed plan-year identifier (plyr_*).

carrier: Optional[str]

Carrier name, or null (e.g. ICHRA).

contribution_strategy: DataContributionStrategy

How the plan year prices contributions: exactly one collection is populated, determined by the plan year’s family (ICHRA vs tier-priced).

contribution_tiers: List[DataContributionStrategyContributionTier]

Coverage tiers and their costs; empty for ICHRA benefits.

benefit_plan_id: str

Prefixed benefit-plan identifier (bpln_*).

benefit_plan_name: str

Benefit plan name.

benefit_plan_tier_name: str

Coverage-tier name.

cost: int

Monthly employee deduction in cents.

cost_per_dependent: int

Monthly employee deduction per dependent, in cents.

coverage_tier: Literal["Unspecified", "EE", "ES", 2 more]
  • Unspecified - Unspecified
  • EE - EE
  • ES - ES
  • EC - EC
  • EF - EF
One of the following:
"Unspecified"
"EE"
"ES"
"EC"
"EF"
dependents_required_in: bool

Whether dependents are required for this tier.

spouse_required_in: bool

Whether a spouse is required for this tier.

ichra_contribution_classes: List[DataContributionStrategyIchraContributionClass]

ICHRA contribution classes; empty for tier-priced benefits.

amount_in_cents: int

Monthly allowance in cents.

compensation: Literal["Unspecified", "Salary", "Hourly"]
  • Unspecified - Unspecified
  • Salary - Salary
  • Hourly - Hourly
One of the following:
"Unspecified"
"Salary"
"Hourly"
contribution_class_id: str

Prefixed contribution-class identifier (iccl_*).

employment: Literal["Unspecified", "Full Time", "Part Time", 2 more]
  • Unspecified - Unspecified
  • Full Time - Full Time
  • Part Time - Part Time
  • Temporary - Temporary
  • Seasonal - Seasonal
One of the following:
"Unspecified"
"Full Time"
"Part Time"
"Temporary"
"Seasonal"
family_status: Literal["Unspecified", "EE", "ES", 2 more]
  • Unspecified - Unspecified
  • EE - EE
  • ES - ES
  • EC - EC
  • EF - EF
One of the following:
"Unspecified"
"EE"
"ES"
"EC"
"EF"
location: Literal["Unspecified", "State"]
  • Unspecified - Unspecified
  • State - State
One of the following:
"Unspecified"
"State"
location_value: Optional[str]

Location matcher value (CSV of state codes), or null.

max_age: Optional[int]

Age-band upper bound, or null.

min_age: Optional[int]

Age-band lower bound, or null.

coverage_end: Optional[date]

Coverage end.

formatdate
coverage_start: date

Coverage start.

formatdate
eligibility_policy: Optional[DataEligibilityPolicy]

The plan year’s active eligibility policy. Mirrors the internal PlanYearEligibilityPolicyDTO but exposes only the public subset (no raw ids, active_in, or timestamps).

rules: List[DataEligibilityPolicyRule]

Eligibility rules; never empty for a valid policy.

compensation_type: Literal["Salary", "Hourly", "All"]
  • Salary - Salary
  • Hourly - Hourly
  • All - All
One of the following:
"Salary"
"Hourly"
"All"
eligible_geographical_location: DataEligibilityPolicyRuleEligibleGeographicalLocation

Geographic matcher.

state_codes: List[str]

States the rule is restricted to; empty when type is All.

type: Literal["All", "StateCodes"]
  • All - All
  • StateCodes - State Codes
One of the following:
"All"
"StateCodes"
employee_class: Literal["Full Time", "Part Time", "Temporary", 4 more]
  • Full Time - Full Time
  • Part Time - Part Time
  • Temporary - Temporary
  • Intern - Intern
  • Seasonal - Seasonal
  • Individual Contractor - Individual Contractor
  • All - All
One of the following:
"Full Time"
"Part Time"
"Temporary"
"Intern"
"Seasonal"
"Individual Contractor"
"All"
termination_n_months: Optional[int]

Months of continued coverage; set only when termination_rule is END_OF_N_MONTHS.

termination_rule: Literal["END_OF_N_MONTHS", "END_OF_PLAN_YEAR"]
  • END_OF_N_MONTHS - End Of N Months
  • END_OF_PLAN_YEAR - End Of Plan Year
One of the following:
"END_OF_N_MONTHS"
"END_OF_PLAN_YEAR"
waiting_period: Optional[Literal["FIRST_OF_FOLLOWING_MONTH", "THIRTY_DAYS", "SIXTY_DAYS"]]
  • FIRST_OF_FOLLOWING_MONTH - First Of Following Month
  • THIRTY_DAYS - Thirty Days
  • SIXTY_DAYS - Sixty Days
One of the following:
"FIRST_OF_FOLLOWING_MONTH"
"THIRTY_DAYS"
"SIXTY_DAYS"
employee_contribution: Optional[DataEmployeeContribution]

Employee contribution range.

max_cents: int

Highest per-tier contribution in cents.

min_cents: int

Lowest per-tier contribution in cents.

employer_contribution: Optional[DataEmployerContribution]

Employer contribution range.

max_cents: int

Highest per-tier contribution in cents.

min_cents: int

Lowest per-tier contribution in cents.

enrollment_rate: DataEnrollmentRate

Enrolled/eligible rate for this plan year.

eligible: int

Employees eligible for this plan year.

enrolled: int

Employees enrolled in this plan year.

percentage: int

enrolled / eligible whole-number percent (0 when none).

family: Literal["mec", "mvp", "ichra", 3 more]
  • mec - Mec
  • mvp - Mvp
  • ichra - Ichra
  • vpc - Vpc
  • dental - Dental
  • vision - Vision
One of the following:
"mec"
"mvp"
"ichra"
"vpc"
"dental"
"vision"
network_names: List[str]

Displayed networks: [“multi”] for ICHRA, otherwise the plan year’s distinct network names.

offered_states: List[str]

Distinct offered state codes.

open_enrollment_end: Optional[date]

Open-enrollment end.

formatdate
open_enrollment_start: date

Open-enrollment start.

formatdate
premium_in_cents: Optional[int]

Monthly premium in cents; only for an ICHRA benefit with effective coverage.

product_name: str

Benefit/product display name.

spd_file_url: Optional[str]

Summary Plan Description (SPD) link, or null.

status: Literal["active", "upcoming", "open_enrollment", "inactive"]
  • active - Active
  • upcoming - Upcoming
  • open_enrollment - Open Enrollment
  • inactive - Inactive
One of the following:
"active"
"upcoming"
"open_enrollment"
"inactive"
year: int

Calendar coverage year.

Get one of an employer's benefit plan years

import os
from vitable_connect import VitableConnect

client = VitableConnect(
    api_key=os.environ.get("VITABLE_CONNECT_API_KEY"),  # This is the default and can be omitted
)
response = client.employers.retrieve_benefit_plan_year(
    benefit_plan_year_id="plyr_abc123def456",
    employer_id="empr_abc123def456",
)
print(response.data)
{
  "data": {
    "benefit_id": "benefit_id",
    "benefit_plan_year_id": "benefit_plan_year_id",
    "carrier": "carrier",
    "contribution_strategy": {
      "contribution_tiers": [
        {
          "benefit_plan_id": "benefit_plan_id",
          "benefit_plan_name": "benefit_plan_name",
          "benefit_plan_tier_name": "benefit_plan_tier_name",
          "cost": 0,
          "cost_per_dependent": 0,
          "coverage_tier": "Unspecified",
          "dependents_required_in": true,
          "spouse_required_in": true
        }
      ],
      "ichra_contribution_classes": [
        {
          "amount_in_cents": 0,
          "compensation": "Unspecified",
          "contribution_class_id": "contribution_class_id",
          "employment": "Unspecified",
          "family_status": "Unspecified",
          "location": "Unspecified",
          "location_value": "location_value",
          "max_age": 0,
          "min_age": 0
        }
      ]
    },
    "coverage_end": "2019-12-27",
    "coverage_start": "2019-12-27",
    "eligibility_policy": {
      "rules": [
        {
          "compensation_type": "Salary",
          "eligible_geographical_location": {
            "state_codes": [
              "string"
            ],
            "type": "All"
          },
          "employee_class": "Full Time"
        }
      ],
      "termination_n_months": 0,
      "termination_rule": "END_OF_N_MONTHS",
      "waiting_period": "FIRST_OF_FOLLOWING_MONTH"
    },
    "employee_contribution": {
      "max_cents": 0,
      "min_cents": 0
    },
    "employer_contribution": {
      "max_cents": 0,
      "min_cents": 0
    },
    "enrollment_rate": {
      "eligible": 0,
      "enrolled": 0,
      "percentage": 0
    },
    "family": "mec",
    "network_names": [
      "string"
    ],
    "offered_states": [
      "string"
    ],
    "open_enrollment_end": "2019-12-27",
    "open_enrollment_start": "2019-12-27",
    "premium_in_cents": 0,
    "product_name": "product_name",
    "spd_file_url": "spd_file_url",
    "status": "active",
    "year": 0
  }
}
Returns Examples
{
  "data": {
    "benefit_id": "benefit_id",
    "benefit_plan_year_id": "benefit_plan_year_id",
    "carrier": "carrier",
    "contribution_strategy": {
      "contribution_tiers": [
        {
          "benefit_plan_id": "benefit_plan_id",
          "benefit_plan_name": "benefit_plan_name",
          "benefit_plan_tier_name": "benefit_plan_tier_name",
          "cost": 0,
          "cost_per_dependent": 0,
          "coverage_tier": "Unspecified",
          "dependents_required_in": true,
          "spouse_required_in": true
        }
      ],
      "ichra_contribution_classes": [
        {
          "amount_in_cents": 0,
          "compensation": "Unspecified",
          "contribution_class_id": "contribution_class_id",
          "employment": "Unspecified",
          "family_status": "Unspecified",
          "location": "Unspecified",
          "location_value": "location_value",
          "max_age": 0,
          "min_age": 0
        }
      ]
    },
    "coverage_end": "2019-12-27",
    "coverage_start": "2019-12-27",
    "eligibility_policy": {
      "rules": [
        {
          "compensation_type": "Salary",
          "eligible_geographical_location": {
            "state_codes": [
              "string"
            ],
            "type": "All"
          },
          "employee_class": "Full Time"
        }
      ],
      "termination_n_months": 0,
      "termination_rule": "END_OF_N_MONTHS",
      "waiting_period": "FIRST_OF_FOLLOWING_MONTH"
    },
    "employee_contribution": {
      "max_cents": 0,
      "min_cents": 0
    },
    "employer_contribution": {
      "max_cents": 0,
      "min_cents": 0
    },
    "enrollment_rate": {
      "eligible": 0,
      "enrolled": 0,
      "percentage": 0
    },
    "family": "mec",
    "network_names": [
      "string"
    ],
    "offered_states": [
      "string"
    ],
    "open_enrollment_end": "2019-12-27",
    "open_enrollment_start": "2019-12-27",
    "premium_in_cents": 0,
    "product_name": "product_name",
    "spd_file_url": "spd_file_url",
    "status": "active",
    "year": 0
  }
}