Oyster HR Benefits API
The Benefits API from Oyster HR — 4 operation(s) for benefits.
Operations 4
GET
/v1/benefits/engagements/{engagement_id}/offerings
Retrieve an employment's available benefits offerings
#
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/oyster-hr:oyster-hr-benefits-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Endpoints Benefits API
version: v1
servers:
- url: https://api.oysterhr.com
description: Production server
- url: https://api-sandbox.oysterhr.com
description: Sandbox server
tags:
- name: Benefits
paths:
/v1/benefits/engagements/{engagement_id}/enrollments:
post:
summary: Request benefits
tags:
- Benefits
description: Provisions benefits for an engagement.
security:
- bearer_auth:
- manage
parameters:
- name: engagement_id
in: path
description: engagement ID
required: true
schema:
type: string
responses:
'200':
description: Successfully requests benefits enrollment
content:
application/json:
examples:
Successfully requests benefits enrollment:
value:
data:
id: A8084119
plan:
id: A4d58b0f
link: http://example.com
name: Pension
providerName: Test nationale nederlanden
category: PENSION
guideUrl: http://example.com/guide
estimatedPrice: null
costSplitAllowed: true
dependentsConfig: ALLOWED
maxDependents: 0
minEmployerContribution: 0
supportedEngagementTypes:
- EMPLOYMENT
- CONTRACT
supportedEorTypes:
- DIRECT
- INDIRECT
mandatory: false
fee: null
package: null
state: REQUESTED
employerContribution:
dependents: 0.35
maxDependentsCovered: 6
teamMember: 0.55
totalCost: null
totalEmployerContributionCost: null
coveragePeriod:
fromDate: '2022-10-15'
toDate: null
schema:
type: object
properties:
data:
$ref: '#/components/schemas/enrollment'
required:
- data
requestBody:
content:
application/json:
schema:
type: object
properties:
planId:
type: string
minLength: 1
pattern: ^[\w+\-]{8,9}$
employerContribution:
type: object
properties:
teamMember:
type: number
minimum: 0
maximum: 100
dependents:
type: number
minimum: 0
maximum: 100
maxDependentsCovered:
type: integer
minimum: 0
required:
- planId
examples:
Successfully requests benefits enrollment:
summary: Successfully requests benefits enrollment
value:
plan_id: A4d58b0f
employer_contribution:
team_member: 0.55
max_dependents_covered: 6
dependents: 0.35
operationId: postV1BenefitsEngagementsByEngagementIdEnrollments
x-operation-id-source: derived
/v1/benefits/engagements/{engagement_id}/offerings:
get:
summary: Retrieve an employment's available benefits offerings
tags:
- Benefits
description: Returns a list of benefits for an employment with a given ID.
security:
- bearer_auth:
- read
parameters:
- name: engagement_id
in: path
description: Employment ID
required: true
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
data:
supplementary:
plans:
- id: A4d58b0f
link: http://example.com
name: Premium
providerName: Safety Wing
category: HEALTH
guideUrl: http://example.com/guide
estimatedPrice:
decimal: '110.00'
currencyCode: EUR
costSplitAllowed: false
dependentsConfig: ALLOWED
maxDependents: 0
minEmployerContribution: 0
supportedEngagementTypes:
- EMPLOYMENT
- CONTRACT
supportedEorTypes:
- DIRECT
- INDIRECT
mandatory: false
fee: null
packages:
- id: A22f3158
name: Essential package
fee: null
plans:
- id: Bbc51b6b
link: http://example.com
name: Standard
providerName: Safety Wing
category: HEALTH
guideUrl: http://example.com/guide
estimatedPrice:
decimal: '70.00'
currencyCode: EUR
costSplitAllowed: false
dependentsConfig: ALLOWED
maxDependents: 0
minEmployerContribution: 0
supportedEngagementTypes:
- EMPLOYMENT
- CONTRACT
supportedEorTypes:
- DIRECT
- INDIRECT
mandatory: false
- id: C3ea2f71
link: http://example.com
name: Benefits
providerName: Canada Life
category: HEALTH
guideUrl: http://example.com/guide
estimatedPrice:
decimal: '150.00'
currencyCode: EUR
costSplitAllowed: false
dependentsConfig: ALLOWED
maxDependents: 0
minEmployerContribution: 0
supportedEngagementTypes:
- EMPLOYMENT
- CONTRACT
supportedEorTypes:
- DIRECT
- INDIRECT
mandatory: false
- id: D4c07300
link: http://example.com
name: Exec Class A
providerName: Aetna Kaiser
category: HEALTH
guideUrl: http://example.com/guide
estimatedPrice:
decimal: '1810.24'
currencyCode: EUR
costSplitAllowed: false
dependentsConfig: ALLOWED
maxDependents: 0
minEmployerContribution: 0
supportedEngagementTypes:
- EMPLOYMENT
- CONTRACT
supportedEorTypes:
- DIRECT
- INDIRECT
mandatory: false
schema:
type: object
properties:
data:
$ref: '#/components/schemas/benefitsOffering'
required:
- data
operationId: getV1BenefitsEngagementsByEngagementIdOfferings
x-operation-id-source: derived
/v1/benefits/enrollments/{id}:
get:
summary: Retrieve an enrollment
tags:
- Benefits
description: Returns a list of benefits for an enrollment with a given ID.
security:
- bearer_auth:
- read
parameters:
- name: id
in: path
description: Enrollment ID
required: true
schema:
type: string
responses:
'200':
description: Successful
content:
application/json:
examples:
Successful:
value:
data:
id: A8084119
plan:
id: A4d58b0f
link: http://example.com
name: Standard
providerName: Safety Wing
category: HEALTH
guideUrl: http://example.com/guide
estimatedPrice:
decimal: '70.00'
currencyCode: EUR
costSplitAllowed: false
dependentsConfig: ALLOWED
maxDependents: 0
minEmployerContribution: 0
supportedEngagementTypes:
- EMPLOYMENT
- CONTRACT
supportedEorTypes:
- DIRECT
- INDIRECT
mandatory: false
fee: null
package: null
state: ENROLLED
employerContribution:
dependents: 100
maxDependentsCovered: null
teamMember: 100
totalCost:
decimal: '10.0'
currencyCode: EUR
totalEmployerContributionCost:
decimal: '10.0'
currencyCode: EUR
coveragePeriod:
fromDate: '2022-10-10'
toDate: null
schema:
type: object
properties:
data:
$ref: '#/components/schemas/enrollment'
required:
- data
operationId: getV1BenefitsEnrollmentsById
x-operation-id-source: derived
/v1/benefits/ruleset:
get:
summary: Retrieve benefits ruleset
tags:
- Benefits
description: Returns the rules and restrictions that will be applied to requests for the benefits provisioning.
security:
- bearer_auth:
- read
responses:
'200':
description: 'Successfully retrieve the ruleset '
content:
application/json:
examples:
'Successfully retrieve the ruleset ':
value:
data:
rulesetId: DEFAULT
scope: {}
schemas:
put:
type: object
properties:
supplementary:
type: object
properties:
plansSettings:
type: array
items:
type: object
properties:
planId:
type: string
minLength: 1
pattern: ^[\w+\-]{8,9}$
employerContribution:
type: object
properties:
teamMember:
type: number
minimum: 0
maximum: 100
dependents:
type: number
minimum: 0
maximum: 100
maxDependentsCovered:
type: integer
minimum: 0
required: []
required:
- planId
required: []
package:
type: object
properties:
id:
type: string
minLength: 1
pattern: ^[\w+\-]{8,9}$
plansSettings:
type: array
items:
type: object
properties:
planId:
type: string
pattern: ^[\w+\-]{8,9}$
employerContribution:
type: object
properties:
teamMember:
type: number
minimum: 0
maximum: 100
dependents:
type: number
minimum: 0
maximum: 100
maxDependentsCovered:
type: integer
minimum: 0
required: []
required:
- planId
required:
- id
required: []
post:
type: object
properties:
planId:
type: string
minLength: 1
pattern: ^[\w+\-]{8,9}$
employerContribution:
type: object
properties:
teamMember:
type: number
minimum: 0
maximum: 100
dependents:
type: number
minimum: 0
maximum: 100
maxDependentsCovered:
type: integer
minimum: 0
required: []
required:
- planId
sources:
categories:
params: {}
operationId: getV1BenefitsRuleset
x-operation-id-source: derived
components:
schemas:
benefitPlan:
properties:
category:
type: string
estimatedPrice:
type:
- object
- 'null'
properties:
currencyCode:
type: string
minLength: 3
maxLength: 3
decimal:
type: string
pattern: ^\d+([.]\d+)?$
required:
- currencyCode
- decimal
fee:
type:
- object
- 'null'
properties:
currencyCode:
type: string
minLength: 3
maxLength: 3
decimal:
type: string
pattern: ^\d+([.]\d+)?$
required:
- currencyCode
- decimal
guideUrl:
type: string
id:
type: string
link:
type: string
name:
type: string
benefitsOffering:
properties:
supplementary:
type: object
properties:
plans:
type: array
items:
$ref: '#/components/schemas/benefitPlan'
packages:
type: array
items:
$ref: '#/components/schemas/benefitPackage'
enrollment:
type: object
properties:
id:
type: string
state:
type: string
plan:
$ref: '#/components/schemas/benefitPlan'
package:
$ref: '#/components/schemas/benefitPackage'
employerContribution:
type:
- object
- 'null'
properties:
dependents:
type:
- number
- 'null'
max_dependents_covered:
type:
- number
- 'null'
teamMember:
type:
- number
- 'null'
totalCost:
type:
- object
- 'null'
properties:
decimal:
type: string
pattern: ^\d+([.]\d+)?$
currencyCode:
type: string
minLength: 3
maxLength: 3
totalEmployerContributionCost:
type:
- object
- 'null'
properties:
decimal:
type: string
pattern: ^\d+([.]\d+)?$
currencyCode:
type: string
minLength: 3
maxLength: 3
coveragePeriod:
type:
- object
- 'null'
properties:
fromDate:
type:
- string
- 'null'
format: date
toDate:
type:
- string
- 'null'
format: date
benefitPackage:
properties:
id:
type: string
fee:
type:
- object
- 'null'
properties:
currencyCode:
type: string
minLength: 3
maxLength: 3
decimal:
type: string
pattern: ^\d+([.]\d+)?$
name:
type: string
plans:
type: array
items:
$ref: '#/components/schemas/benefitPlan'
securitySchemes:
bearer_auth:
type: http
scheme: bearer
x-provenance:
method: searched
source: https://docs.oysterhr.com/reference
harvested: '2026-10-14'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://docs.oysterhr.com/reference/delete_v1-bank-accounts-id.md
- https://docs.oysterhr.com/reference/delete_v1-consent-grants.md
- https://docs.oysterhr.com/reference/delete_v1-expenses-id.md
- https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-commission-plan.md
- https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-document-document-id.md
- https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id-work-permit.md
- https://docs.oysterhr.com/reference/delete_v1-hiring-employments-id.md
- https://docs.oysterhr.com/reference/delete_v1-payments-charge-groups-id-wire-sent.md
- https://docs.oysterhr.com/reference/delete_v1-payroll-changes-id.md
- https://docs.oysterhr.com/reference/delete_v1-time-tracking-time-sheets-entries-id.md
- https://docs.oysterhr.com/reference/delete_v1-time-tracking-time-sheets-id.md
- https://docs.oysterhr.com/reference/delete_v1-webhooks-id.md
- https://docs.oysterhr.com/reference/get_v1-bank-accounts-id.md
- https://docs.oysterhr.com/reference/get_v1-bank-accounts-rulesets.md
- https://docs.oysterhr.com/reference/get_v1-bank-accounts.md
- https://docs.oysterhr.com/reference/get_v1-benefits-engagements-engagement-id-offerings.md
- https://docs.oysterhr.com/reference/get_v1-benefits-enrollments-id.md
- https://docs.oysterhr.com/reference/get_v1-benefits-ruleset.md
- https://docs.oysterhr.com/reference/get_v1-company.md
- https://docs.oysterhr.com/reference/get_v1-contract-changes-id.md
- https://docs.oysterhr.com/reference/get_v1-contract-changes-rulesets.md
- https://docs.oysterhr.com/reference/get_v1-contract-changes.md
- https://docs.oysterhr.com/reference/get_v1-credit-notes-identifier.md
- https://docs.oysterhr.com/reference/get_v1-credit-notes-sources-statuses.md
- https://docs.oysterhr.com/reference/get_v1-credit-notes-sources-types.md
- https://docs.oysterhr.com/reference/get_v1-credit-notes.md
- https://docs.oysterhr.com/reference/get_v1-departments.md
- https://docs.oysterhr.com/reference/get_v1-engagements-id-allowances.md
- https://docs.oysterhr.com/reference/get_v1-engagements-id-bonuses.md
- https://docs.oysterhr.com/reference/get_v1-engagements-id-documents.md
- https://docs.oysterhr.com/reference/get_v1-engagements-id-identity-verification.md
- https://docs.oysterhr.com/reference/get_v1-engagements-id-payslips.md
- https://docs.oysterhr.com/reference/get_v1-engagements-id.md
- https://docs.oysterhr.com/reference/get_v1-engagements.md
- https://docs.oysterhr.com/reference/get_v1-expenses-id.md
- https://docs.oysterhr.com/reference/get_v1-expenses-ruleset.md
- https://docs.oysterhr.com/reference/get_v1-expenses-rulesets-id-sources-categories.md
- https://docs.oysterhr.com/reference/get_v1-expenses-rulesets-id.md
- https://docs.oysterhr.com/reference/get_v1-expenses.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-agreements-agreement-id.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-agreements.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-cost-estimates-annually.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-cost-estimates-monthly.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-onboarding-form-documents-field-or-document-id.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-onboarding-form.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id-tasks.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-id.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-onboarding-form.md
- https://docs.oysterhr.com/reference/get_v1-hiring-employments-rulesets.md
- https://docs.oysterhr.com/reference/get_v1-hiring-role-types.md
- https://docs.oysterhr.com/reference/get_v1-invoices-identifier-breakdown.md
- https://docs.oysterhr.com/reference/get_v1-invoices-identifier.md
- https://docs.oysterhr.com/reference/get_v1-invoices-sources-statuses.md
- https://docs.oysterhr.com/reference/get_v1-invoices-sources-types.md
- https://docs.oysterhr.com/reference/get_v1-invoices.md
- https://docs.oysterhr.com/reference/get_v1-meta-operations-operation-key.md
- https://docs.oysterhr.com/reference/get_v1-offboardings-id-agreements.md
- https://docs.oysterhr.com/reference/get_v1-offboardings-id.md
- https://docs.oysterhr.com/reference/get_v1-offboardings-payroll-team-members-terminations-rulesets.md
- https://docs.oysterhr.com/reference/get_v1-offboardings-sources-employment-type-categories.md
- https://docs.oysterhr.com/reference/get_v1-offboardings-sources-employment-type-pay-types.md
- https://docs.oysterhr.com/reference/get_v1-offboardings.md
- https://docs.oysterhr.com/reference/get_v1-payments-charge-groups-id-charges.md
- https://docs.oysterhr.com/reference/get_v1-payments-charge-groups-id.md
- https://docs.oysterhr.com/reference/get_v1-payments-charge-groups.md
- https://docs.oysterhr.com/reference/get_v1-payments-charges-id.md
- https://docs.oysterhr.com/reference/get_v1-payments-payouts-id.md
- https://docs.oysterhr.com/reference/get_v1-payroll-changes-id.md
- https://docs.oysterhr.com/reference/get_v1-payroll-changes-ruleset.md
- https://docs.oysterhr.com/reference/get_v1-payroll-changes-rulesets-default-sources-types.md
- https://docs.oysterhr.com/reference/get_v1-payroll-changes-rulesets-default.md
- https://docs.oysterhr.com/reference/get_v1-payroll-changes-sources-types.md
- https://docs.oysterhr.com/reference/get_v1-payroll-changes.md
- https://docs.oysterhr.com/reference/get_v1-payroll-id-records.md
- https://docs.oysterhr.com/reference/get_v1-payroll-id.md
- https://docs.oysterhr.com/reference/get_v1-payroll.md
- https://docs.oysterhr.com/reference/get_v1-public-holidays.md
- https://docs.oysterhr.com/reference/get_v1-reseller-customers.md
- https://docs.oysterhr.com/reference/get_v1-time-off-entitlements-id.md
- https://docs.oysterhr.com/reference/get_v1-time-off-entitlements.md
- https://docs.oysterhr.com/reference/get_v1-time-off-requests-id.md
- https://docs.oysterhr.com/reference/get_v1-time-off-requests.md
- https://docs.oysterhr.com/reference/get_v1-time-tracking-rulesets-engagement-id-sources-source-type.md
- https://docs.oysterhr.com/reference/get_v1-time-tracking-rulesets-engagement-id.md
- https://docs.oysterhr.com/reference/get_v1-time-tracking-time-sheets-id.md
- https://docs.oysterhr.com/reference/get_v1-time-tracking-time-sheets.md
- https://docs.oysterhr.com/reference/get_v1-webhooks-dispatches.md
- https://docs.oysterhr.com/reference/get_v1-webhooks.md
- https://docs.oysterhr.com/reference/patch_v1-bank-accounts-id.md
- https://docs.oysterhr.com/reference/patch_v1-employments-id-personal-details.md
- https://docs.oysterhr.com/reference/patch_v1-hiring-employments-id-onboarding-form.md
- https://docs.oysterhr.com/reference/patch_v1-hiring-employments-id.md
- https://docs.oysterhr.com/reference/patch_v1-payroll-changes-id.md
- https://docs.oysterhr.com/reference/patch_v1-reseller-customers-id.md
- https://docs.oysterhr.com/reference/patch_v1-time-tracking-time-sheets-entries-id.md
- https://docs.oysterhr.com/reference/patch_v1-webhooks-id.md
- https://docs.oysterhr.com/reference/post_v1-bank-accounts.md
- https://docs.oysterhr.com/reference/post_v1-benefits-engagements-engagement-id-enrollments.md
- https://docs.oysterhr.com/reference/post_v1-consent-grants.md
- https://docs.oysterhr.com/reference/post_v1-contract-changes-id-cancel.md
- https://docs.oysterhr.com/reference/post_v1-contract-changes.md
- https://docs.oysterhr.com/reference/post_v1-engagements-id-identity-verification-approved.md
- https://docs.oysterhr.com/reference/post_v1-engagements-id-identity-verification-declined.md
- https://docs.oysterhr.com/reference/post_v1-engagements-id-identity-verification-sessions.md
- https://docs.oysterhr.com/reference/post_v1-expenses-id-approve.md
- https://docs.oysterhr.com/reference/post_v1-expenses-id-decline.md
- https://docs.oysterhr.com/reference/post_v1-expenses.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-agreements-agreement-id-verify.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-commission-plan.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-document.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-onboarding-form-complete.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-submit.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-team-member-invite.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments-id-work-permit.md
- https://docs.oysterhr.com/reference/post_v1-hiring-employments.md
- https://docs.oysterhr.com/reference/post_v1-invoices-identifier-approve.md
- https://docs.oysterhr.com/reference/post_v1-invoices-identifier-dispute.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-contractors-resignations.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-contractors-terminations.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-employments-resignations.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-employments-terminations.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-id-cancellation.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-id-documents.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-id-initiate.md
- https://docs.oysterhr.com/reference/post_v1-offboardings-payroll-team-members-terminations.md
- https://docs.oysterhr.com/reference/post_v1-payments-charge-groups-id-wire-sent.md
- https://docs.oysterhr.com/reference/post_v1-payroll-changes.md
- https://docs.oysterhr.com/reference/post_v1-reseller-customers.md
- https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-approve.md
- https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-attachment.md
- https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-cancel.md
- https://docs.oysterhr.com/reference/post_v1-time-off-requests-id-reject.md
- https://docs.oysterhr.com/reference/post_v1-time-off-requests.md
- https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets-entries.md
- https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets-id-confirm.md
- https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets-id-submit.md
- https://docs.oysterhr.com/reference/post_v1-time-tracking-time-sheets.md
- https://docs.oysterhr.com/reference/post_v1-webhooks-id-test.md
- https://docs.oysterhr.com/reference/post_v1-webhooks.md
- https://docs.oysterhr.com/reference/put_v1-hiring-employments-id-onboarding-form-documents-field-id.md
merge:
pages: 140
deduped: 378
conflicts_kept_first: 0