Skip to content

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.

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 os
from alter_sdk import App
from 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()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Retrieve Benefits for Employee — 200 response body

Referenced models: Retrieve Benefits for Employee — 200 response body

13 more schemas are linked from the tables above, on the schema pages.

Retrieve Benefits for Employee — 200 response body
FieldTypePresenceDescription and constraints
$objectRoot
dataarrayRequired within parentList of contracts with their associated benefits. An employee may have benefits across multiple contracts if they have more than one active engagement.
data[]ModelEach itemExpand 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
FieldTypePresenceDescription and constraints
$objectRoot
benefitsarrayRequired within parentAll 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[]ModelEach itemExpand Retrieve Benefits for Employee — 200 response body — data item benefits item
contract_idstringRequired within parentUnique 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.
currencystringRequired within parentISO 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
FieldTypePresenceDescription and constraints
$objectRoot
benefit_type_codestringOptionalJurisdiction-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_typestringOptionalWorkforce 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_groupstringOptionalWho 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.
descriptionstringRequired within parentPlain-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_datestringOptionalDate 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_contributionModelOptionalExpand 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_contributionModelOptionalExpand 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_dateJSONOptional
end_date (anyOf 1)stringAlternativeDate 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)nullAlternativeDate 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_detailsModelRequired within parentExpand 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_statusstringOptionalEnrollment 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_windowModelOptionalExpand 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).
idstringOptionalUnique identifier (UUID) for this benefit instance. Use this when referencing the benefit in subsequent API calls.
Format: uuid
namestringRequired within parentHuman-readable display name of the benefit (e.g. 'Healthcare', 'Dental', '401(k)'). Suitable for display in UI.
organization_selectionModelRequired within parentExpand 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_urlJSONOptional
plan_url (anyOf 1)stringAlternativeURL 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)nullAlternativeURL 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_namestringOptionalDisplay name of the insurance carrier or benefit provider administering this plan (for example Allianz, Cigna, ManuLife).
provider_website_urlstringOptionalPublic 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.
statusstringRequired within parentEnrollment 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.
typeJSONRequired within parent
type (anyOf 1)stringAlternativeHigh-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)nullAlternativeHigh-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
FieldTypePresenceDescription and constraints
$JSONRootRaw 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)JSONAlternative
$ (anyOf 1) (anyOf 1)numberAlternativeFormat: double
$ (anyOf 1) (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
$ (anyOf 2)stringAlternative

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"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.