Deel: Retrieve Benefits for Employee — 200 response body — data item benefits item

API reference · Contract 2026-10-27

SDK schema: Retrieve Benefits for Employee — 200 response body — data item benefits item

Field	Type	Presence	Description and constraints
$	object	Root
benefit_type_code	string	Optional	Jurisdiction-aware classification code for this benefit. Use this (not only `type`) when product logic must differ by country — for example retirement: `401_K` in the US versus `OCCUPATIONAL_PENSION` in the UK and Ireland. Other common values include HEALTHCARE, DENTAL, VISION, LIFE_INSURANCE, ACCIDENT_INSURANCE, and CRITICAL_ILLNESS; the full set may expand as new benefit types are added.
contract_type	string	Optional	Workforce product for the contract this benefit belongs to. EOR — Employer of Record; Deel is the legal employer. GP — Global Payroll; the client is the legal employer and Deel runs payroll. PEO — Professional Employer Organization (US co-employment). EMBEDDED — payroll or HR through an embedded partner integration.
coverage_group	string	Optional	Who is covered under this benefit, derived from enrolled dependents on the contract benefit. EMPLOYEE = employee only. EMPLOYEE_AND_SPOUSE = employee plus legal spouse. EMPLOYEE_AND_DOMESTIC_PARTNER = employee plus registered domestic partner where applicable. EMPLOYEE_AND_CHILD = employee plus dependent child coverage structured as a single-child tier. EMPLOYEE_AND_CHILDREN = employee plus all enrolled children. EMPLOYEE_AND_FAMILY = employee plus spouse or partner and children (full family tier) per plan rules.
description	string	Required within parent	Plain-text explanation of what this benefit covers and why it matters to the employee. Suitable for display in a benefits overview UI or summary card.
effective_date	string	Optional	Date from which this benefit offering is in effect for this employee in this response (ISO 8601, `YYYY-MM-DD`). The benefit offering’s offered-at date when present — not the same as contract coverage start or plan-specific coverage start dates inside enrollment.
employee_contribution	Model	Optional	Expand Retrieve Benefits for Employee — 200 response body — data item benefits item employee contribution Recurring portion of plan cost collected from the employee’s pay for this benefit. Expressed with calculation metadata (`type`, `value`), resolved `amount`, `currency`, and `frequency`. For a given period, `employee_contribution.amount` plus `employer_contribution.amount` reflects the split of premium or plan cost represented here; use `enrollment_details` cycle fields when you need billed totals for the current cycle.
employer_contribution	Model	Optional	Expand Retrieve Benefits for Employee — 200 response body — data item benefits item employer contribution Recurring employer-paid portion for this benefit, same shape as `employee_contribution`. Together with `employee_contribution.amount`, describes how premium or plan cost is split for the modeled period; billed totals for the active cycle may also appear under `enrollment_details`.
end_date	JSON	Optional
end_date (anyOf 1)	string	Alternative	Date on which this benefit’s coverage ends (ISO 8601, `YYYY-MM-DD`). Benefit record’s effective end, termination, or offer end where applicable. Null or absent when no definitive end date is set on this record (coverage may still change if the contract or offering is updated).
end_date (anyOf 2)	null	Alternative	Date on which this benefit’s coverage ends (ISO 8601, `YYYY-MM-DD`). Benefit record’s effective end, termination, or offer end where applicable. Null or absent when no definitive end date is set on this record (coverage may still change if the contract or offering is updated).
enrollment_details	Model	Required within parent	Expand Retrieve Benefits for Employee — 200 response body — data item benefits item enrollment details Details about the specific plan and provider the employee is currently enrolled in, along with the cost breakdown for the current billing cycle. Reflects the employee’s actual enrollment, which may differ from organization_selection if the employee made their own plan choice.
enrollment_status	string	Optional	Enrollment lifecycle state for this benefit. Always matches `status` in this API version; both are returned so integrations can use the explicit `enrollment_status` name. PENDING = benefit exists but no enrollment action yet. AWAITING_ENROLLMENT = employee must complete enrollment while an enrollment window applies. AWAITING_CARRIER_CONFIRMATION = submission received; awaiting carrier or administrator confirmation. AWAITING_CONTRACT_ACTIVATION = enrollment cannot complete until the underlying employment contract is active. ENROLLED = active coverage. OPTED_OUT = employee stopped or waived the coverage. TERMINATED = stopped before natural expiry. EXPIRED = coverage window has ended.
enrollment_window	Model	Optional	Expand Retrieve Benefits for Employee — 200 response body — data item benefits item enrollment window Calendar window during which the employee may enroll in, change, or opt out of this benefit. Omitted when no window is returned (enrollment changes are then not accepted until a new window opens, for example open enrollment, a qualifying life event, or a new-hire cycle per employer configuration).
id	string	Optional	Unique identifier (UUID) for this benefit instance. Use this when referencing the benefit in subsequent API calls. Format: uuid
name	string	Required within parent	Human-readable display name of the benefit (e.g. ‘Healthcare’, ‘Dental’, ‘401(k)’). Suitable for display in UI.
organization_selection	Model	Required within parent	Expand Retrieve Benefits for Employee — 200 response body — data item benefits item organization selection The plan and provider the client organization has configured as the default offering for this benefit type. This reflects the employer’s choice, which may differ from enrollment_details if the employee hasn’t enrolled yet or selected a different option during open enrollment.
plan_url	JSON	Optional
plan_url (anyOf 1)	string	Alternative	URL to this specific plan’s portal or documentation — for example, a plan summary PDF, carrier-hosted plan detail page, or plan materials. Distinct from `provider_website_url` (the provider organization as a whole) and `home_page_url` (employee portal for claims and ID cards).
plan_url (anyOf 2)	null	Alternative	URL to this specific plan’s portal or documentation — for example, a plan summary PDF, carrier-hosted plan detail page, or plan materials. Distinct from `provider_website_url` (the provider organization as a whole) and `home_page_url` (employee portal for claims and ID cards).
provider_name	string	Optional	Display name of the insurance carrier or benefit provider administering this plan (for example Allianz, Cigna, ManuLife).
provider_website_url	string	Optional	Public marketing or corporate website for the carrier or administrator. For the employee-facing portal (claims, ID cards, provider search), use `home_page_url` when enrolled.
status	string	Required within parent	Enrollment lifecycle state for this benefit. Populated with the same value as `enrollment_status` (both fields are returned for backward compatibility). ENROLLED = active, claimable coverage. OPTED_OUT = employee stopped or waived the coverage. TERMINATED = cancelled mid-contract. EXPIRED = coverage period ended. PENDING, AWAITING_ENROLLMENT, AWAITING_CARRIER_CONFIRMATION, and AWAITING_CONTRACT_ACTIVATION indicate transitional or pre-active states; see `enrollment_status` for the same enumeration and definitions.
type	JSON	Required within parent
type (anyOf 1)	string	Alternative	High-level category of the benefit (e.g. HEALTHCARE, DENTAL, VISION). May be null if uncategorized. Use benefit_type_code for a more specific, jurisdiction-aware value.
type (anyOf 2)	null	Alternative	High-level category of the benefit (e.g. HEALTHCARE, DENTAL, VISION). May be null if uncategorized. Use benefit_type_code for a more specific, jurisdiction-aware value.

Referenced models: Retrieve Benefits for Employee — 200 response body — data item benefits item employee contribution, Retrieve Benefits for Employee — 200 response body — data item benefits item employer contribution, Retrieve Benefits for Employee — 200 response body — data item benefits item enrollment details, Retrieve Benefits for Employee — 200 response body — data item benefits item enrollment window, Retrieve Benefits for Employee — 200 response body — data item benefits item organization selection