Skip to navigation
API ReferencePolicies

Retrieve a policy

Retrieves a policy object.

Authentication

AuthorizationBearer
Authorization header using the Bearer scheme

Path parameters

policy_idstringRequiredformat: "p_.+"

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.

Response

OK
idstringformat: "p_.+"

Unique identifier for the policy. Prefixed with p_.

employee_idstringformat: "ee_.+"

Identifier of the employee associated with this policy. Prefixed with ee_.

group_policy_idstringformat: "gp_.+"

Identifier of the group policy id associated with this policy. Prefixed with gp_.

bundling_typeenum
Indicates how this policy is bundled within a group
Allowed values:
statusenum
Current lifecycle state of the policy
Allowed values:
group_idstringformat: "gr_.+"

Identifier of the group associated with this policy. Prefixed with gr_.

providerobject
Provider information for this policy
planobject
Plan information for this policy
start_datedate

Policy start (effective) date in ISO 8601 (YYYY-MM-DD)

typeenum

Policy type. Determines which sub-object is populated.

Allowed values:
disclosureslist of objects
Disclosures associated with this policy.
end_datedate or nullOptional

Policy end date (inclusive) in ISO 8601, or null if open-ended

cancellation_datedate or nullOptional

Date the policy was cancelled (if applicable)

opted_out_atdatetime or nullOptional

UTC timestamp of the moment the member opted out of this policy during the cooling-off window. Null when the policy is still running, and null when it ended any other way — an administrator cancelling it, the employee being offboarded, or the term expiring — even though those also set cancellation_date. Providers that only record the calendar day of an opt-out report midnight UTC.

health_insuranceobjectOptional

Health insurance–specific fields (present when type=health_insurance)

life_assuranceobjectOptional

Life assurance–specific fields (present when type=life_assurance). Carries no member list: life cover is policyholder-only.

objectstringOptionalRead-only
Object type

Errors

404
Not Found Error