Create new plan year

post/v1/benefit-products/{benefit_product_id}/plan-years

Creates a new plan year configuration for a benefit product and employer. Configures coverage period dates, open enrollment window, and contribution structure. All monetary values must be in cents.

Path ParametersExpand Collapse

benefit_product_id: string

Body ParametersExpand Collapse

contribution_classes: array of object { employee_contribution_cents, employer_contribution_cents, employment, family_status }

List of contribution classes (at least one required)

employee_contribution_cents: number

Employee's monthly contribution in cents

minimum0

employer_contribution_cents: number

Employer's monthly contribution in cents

minimum0

employment: string

Employment type (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: string

Coverage end date

formatdate

coverage_start: string

Coverage start date

formatdate

employer_id: string

Employer ID this plan year is for (empr_*)

open_enrollment_end: string

Open enrollment end date

formatdate

open_enrollment_start: string

Open enrollment start date

formatdate

ReturnsExpand Collapse

PlanYear = object { id, benefit_product_id, contribution_classes, 9 more }

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: string

Unique plan year identifier with 'plyr_' prefix

benefit_product_id: string

ID of the benefit product (bprd_*)

contribution_classes: array of object { id, employee_contribution_cents, employer_contribution_cents, 2 more }

List of contribution classes defining eligibility tiers and cost structures

id: string

Unique contribution class identifier

employee_contribution_cents: number

Employee's monthly contribution amount in cents

employer_contribution_cents: number

Employer's monthly contribution amount in cents

employment: string

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: string

Date when benefit coverage ends

formatdate

coverage_start: string

Date when benefit coverage begins

formatdate

created_at: string

Timestamp when the plan year was created

formatdate-time

employer_id: string

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

open_enrollment_end_date: string

Date when open enrollment period ends

formatdate

open_enrollment_start_date: string

Date when open enrollment period begins

formatdate

plans: array of object { id, carrier_plan_id, monthly_premium_cents, 4 more }

List of insurance plans available in this plan year

id: string

Unique plan identifier with 'plan_' prefix

carrier_plan_id: string

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

monthly_premium_cents: number

Base monthly premium in cents

name: string

Display name of the insurance plan

deductible_cents: optional number

Annual deductible amount in cents

out_of_pocket_max_cents: optional number

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: string

Timestamp when the plan year was last updated

formatdate-time

Create new plan year

curl https://api.vitablehealth.com/v1/benefit-products/$BENEFIT_PRODUCT_ID/plan-years \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $VITABLE_connect_API_API_KEY" \
    -d '{
          "contribution_classes": [
            {
              "employee_contribution_cents": 0,
              "employer_contribution_cents": 0,
              "employment": "employment",
              "family_status": "Unspecified"
            }
          ],
          "coverage_end": "2019-12-27",
          "coverage_start": "2019-12-27",
          "employer_id": "employer_id",
          "open_enrollment_end": "2019-12-27",
          "open_enrollment_start": "2019-12-27"
        }'

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