API ReferencePlans

Retrieve a plan

Retrieves a plan object by its ID.

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Path parameters

plan_idstringRequiredformat: "pl_.+"

Headers

X-Platform-IdstringOptional

The target platform id. Required only when calling with a dashboard (WorkOS AuthKit) access token instead of a platform API key — the token carries no platform claim, so the caller must say which platform it means. Ignored for platform API key / embed session token callers.

Query parameters

group_idstringOptionalformat: "gr_.+"

When provided together with start_date, per-plan eligibility counts are included in the response. Silently ignored if not paired with start_date.

start_datedateOptional

Reference date used to compute employee age when evaluating eligibility. Required together with group_id for counts to be included.

Response

OK
idstringformat: "pl_.+"

Unique identifier for the plan. Prefixed with pl_.

typeenum
The benefit type of the plan.
namestring
The name of the plan.
descriptionstring
Description of the plan.
countryenum
The country this plan is available in.
providerobject
The provider offering this plan.
documentslist of objects

List of plan documents (e.g., IPIDs, T&Cs).

employer_eligibility_criterialist of objects
Eligibility criteria that employers must meet.
employee_eligibility_criterialist of objects
Eligibility criteria that employees must meet.
disclosureslist of objects
Disclosures associated with this plan.
available_fromdate

The date from which this plan is available (inclusive).

objectstringOptionalRead-only

Object type. Always plan.

health_insuranceobjectOptional

Health insurance-specific details. Only populated when type is health_insurance.

indicative_pricingobjectOptional

Average monthly guide prices used when exact catalog pricing is unavailable. Actual premiums may be higher or lower based on the whole policy; these values are for comparison only and must not be used in premium calculations.

available_todate or nullOptional

The date until which this plan is available (inclusive). Null if the plan has no end date.

coverage_optionslist of objects or nullOptional
Coverage options available for this plan, organized by scope and input type.
eligible_countinteger or nullOptional

Number of employees in the queried group eligible for this plan as-of start_date. Only present when both group_id and start_date query parameters are provided.

ineligible_countinteger or nullOptional

Number of employees in the queried group ineligible for this plan as-of start_date. Only present when both group_id and start_date query parameters are provided.

total_countinteger or nullOptional

Total employees in the queried group. Only present when both group_id and start_date query parameters are provided.

Errors

404
Not Found Error