Deel: Retrieve Benefits for Employee
Deel eorWorkerBenefits.getEorworkerBenefits: arguments, response, policy and SDK examples.
← EOR worker benefits operations · Get started
Operation deel.eorworkerbenefits_geteorworkerbenefits
Provider route: GET /eor/worker/benefits. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/deel with npm, or alter-sdk-deel with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { DeelIntegration } from "@alter-ai/deel";
async function execute(input: Parameters<DeelIntegration["eorWorkerBenefits"]["getEorworkerBenefits"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new DeelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.eorWorkerBenefits.getEorworkerBenefits(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_deel import DeelIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = DeelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.eor_worker_benefits.get_eorworker_benefits(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Retrieve Benefits for Employee — 200 response body |
Referenced models: Retrieve Benefits for Employee — 200 response body
Schemas
Section titled “Schemas”13 more schemas are linked from the tables above, on the schema pages.
Retrieve Benefits for Employee — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | List of contracts with their associated benefits. An employee may have benefits across multiple contracts if they have more than one active engagement. |
data[] | Model | Each item | Expand Retrieve Benefits for Employee — 200 response body — data item |
Referenced models: Retrieve Benefits for Employee — 200 response body — data item
Retrieve Benefits for Employee — 200 response body — data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
benefits | array | Required within parent | All benefits associated with this contract, regardless of enrollment status. Includes benefits the employee is enrolled in, has opted out of, or is pending enrollment for. |
benefits[] | Model | Each item | Expand Retrieve Benefits for Employee — 200 response body — data item benefits item |
contract_id | string | Required within parent | Unique identifier for the employment contract these benefits are associated with. Use to correlate benefits with a specific contract when the employee has multiple active engagements. |
currency | string | Required within parent | ISO 4217 currency code for all monetary amounts within this contract's benefits (e.g. 'USD', 'CAD', 'GBP'). Applies to all cost and contribution fields in this contract grouping. |
Referenced models: Retrieve Benefits for Employee — 200 response body — data item benefits item
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
Retrieve Benefits for Employee — 200 response body — data item benefits item employee contribution value value value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | Raw contribution input from configuration or upstream systems; may be a number or string (for example `"1.23"`). Use `amount` for display and arithmetic — it is the normalized numeric value in `currency` per `frequency`. |
$ (anyOf 1) | JSON | Alternative | |
$ (anyOf 1) (anyOf 1) | number | Alternative | Format: double |
$ (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
$ (anyOf 2) | string | Alternative |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: deel.eorworkerbenefits_geteorworkerbenefits. Catalog operation: eorworkerbenefits_geteorworkerbenefits. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["benefits:read"]
Pinned headers: {"X-Version": "2026-01-01"}