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

List an employer's benefit plan years

GET/v1/employers/{employer_id}/benefit-plan-years

Returns the employer’s benefit plan years (all years, or one when year is given), each with its benefits, offered states, benefit families, and the year-level enrollment roll-up. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404.

Path ParametersExpand Collapse
employer_id: string

Unique employer identifier (empr_*)

ReturnsExpand Collapse
data: array of { benefit_id, benefit_plan_year_id, carrier, 15 more }
benefit_id: string

Prefixed benefit identifier (bprd_*).

benefit_plan_year_id: string

Prefixed plan-year identifier (plyr_*).

carrier: string

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

coverage_end: string

Coverage end.

formatdate
coverage_start: string

Coverage start.

formatdate
employee_contribution: { max_cents, min_cents }

Employee contribution range.

max_cents: number

Highest per-tier contribution in cents.

min_cents: number

Lowest per-tier contribution in cents.

employer_contribution: { max_cents, min_cents }

Employer contribution range.

max_cents: number

Highest per-tier contribution in cents.

min_cents: number

Lowest per-tier contribution in cents.

enrollment_rate: { eligible, enrolled, percentage }

Enrolled/eligible rate for this plan year.

eligible: number

Employees eligible for this plan year.

enrolled: number

Employees enrolled in this plan year.

percentage: number

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

family: "mec" or "mvp" or "ichra" or 3 more
  • mec - Mec
  • mvp - Mvp
  • ichra - Ichra
  • vpc - Vpc
  • dental - Dental
  • vision - Vision
One of the following:
"mec"
"mvp"
"ichra"
"vpc"
"dental"
"vision"
is_current: boolean

Whether this is the current plan year.

network_names: array of string

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

offered_states: array of string

Distinct offered state codes.

open_enrollment_end: string

Open-enrollment end.

formatdate
open_enrollment_start: string

Open-enrollment start.

formatdate
premium_in_cents: number

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

product_name: string

Benefit/product display name.

status: "active" or "upcoming" or "open_enrollment" or "inactive"
  • active - Active
  • upcoming - Upcoming
  • open_enrollment - Open Enrollment
  • inactive - Inactive
One of the following:
"active"
"upcoming"
"open_enrollment"
"inactive"
year: number

Calendar coverage year.

List an employer's benefit plan years

curl https://api.vitablehealth.com/v1/employers/$EMPLOYER_ID/benefit-plan-years \
    -H "Authorization: Bearer $VITABLE_CONNECT_API_KEY"
{
  "data": [
    {
      "benefit_id": "benefit_id",
      "benefit_plan_year_id": "benefit_plan_year_id",
      "carrier": "carrier",
      "coverage_end": "2019-12-27",
      "coverage_start": "2019-12-27",
      "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",
      "is_current": true,
      "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",
      "status": "active",
      "year": 0
    }
  ]
}
Returns Examples
{
  "data": [
    {
      "benefit_id": "benefit_id",
      "benefit_plan_year_id": "benefit_plan_year_id",
      "carrier": "carrier",
      "coverage_end": "2019-12-27",
      "coverage_start": "2019-12-27",
      "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",
      "is_current": true,
      "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",
      "status": "active",
      "year": 0
    }
  ]
}