Skip to navigation
API ReferenceEmployers

List Benefit Plan Year Enrollments

Returns a paginated list of every member with an enrollment in one of an employer’s plan years, any election status: what they elected, where their coverage stands, dependent count, carrier, plan, tier, and the plan’s total monthly cost. The caller must be authorized for the employer empr_<...>; an unknown or unauthorized employer, or an unknown plan year plyr_<...>, returns 404.

Authentication

AuthorizationBearer

API Key or Access Token authentication using Bearer token in Authorization header. API keys use the vit_apk_ prefix, access tokens use the vit_at_ prefix.

Path parameters

benefit_plan_year_idstringRequired

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

employer_idstringRequired

Unique employer identifier (empr_*).

Headers

X-Vitable-OrganizationstringOptional

Organization to act as for this request (e.g. org_SGVsbG8gV29ybGQ). Optional when your credentials reach a single organization. Required when they reach several — omitting it then returns 400 organization_required. A malformed value returns 400 invalid_organization_header, and naming an organization you do not have access to returns 403 organization_access_denied.

Query parameters

election_statuslist of enumsOptional
Filter by election status. Repeat the parameter to match several.
Allowed values:
limitintegerOptional1-100Defaults to 20

Items per page (default: 20, max: 100)

pageintegerOptional>=1Defaults to 1

Page number (default: 1)

searchstringOptional

Case-insensitive search. Matches member name partially, and the member_id exactly — either your own reference id or the prefixed grpmbr_<...> id.

Response headers

X-RateLimit-Limitinteger
Maximum number of requests allowed within the rate limit window
X-RateLimit-Remaininginteger
Number of requests remaining in the current rate limit window
X-RateLimit-Resetinteger

Unix timestamp (seconds) when the rate limit window resets

Response

datalist of objects
This page of plan year enrollments.
paginationobject

Page metadata. Request the next page by incrementing page.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error