## 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.

### Parameters

- `employer_id: str`

  Unique employer identifier (empr_*)

- `benefit_plan_year_id: str`

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

### Returns

- `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

          - `"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

          - `"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

          - `"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

          - `"Unspecified"`

          - `"EE"`

          - `"ES"`

          - `"EC"`

          - `"EF"`

        - `location: Literal["Unspecified", "State"]`

          * `Unspecified` - Unspecified
          * `State` - State

          - `"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.

    - `coverage_start: date`

      Coverage start.

    - `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

          - `"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

            - `"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

          - `"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

        - `"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

        - `"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

      - `"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.

    - `open_enrollment_start: date`

      Open-enrollment start.

    - `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

      - `"active"`

      - `"upcoming"`

      - `"open_enrollment"`

      - `"inactive"`

    - `year: int`

      Calendar coverage year.

### Example

```python
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)
```

#### Response

```json
{
  "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
  }
}
```