Remote Benefit Offers By Employment API
The Benefit Offers By Employment API from Remote — 1 operation(s) for benefit offers by employment.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Benefit Offers By Employment API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Benefit Offers By Employment
paths:
/v1/benefit-offers:
get:
callbacks: {}
deprecated: false
description: 'List benefit offers by employment.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View benefit offers (`benefit_offer:read`) | Manage benefit offers (`benefit_offer:write`) |
'
operationId: get_v1_benefit-offers
parameters:
- description: 'Requires a Company-scoped access token obtained through the Authorization Code flow or the Refresh Token flow.
The refresh token needs to have been obtained through the Authorization Code flow.
'
example: Bearer <COMPANY-SCOPED ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BenefitOfferByEmploymentResponse'
description: Success
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- benefit_offer:read
- benefit_offer:write
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- benefit_offer:read
- benefit_offer:write
- company_admin
- all:write
- all:read
summary: List Benefit Offers By Employment
tags:
- Benefit Offers By Employment
components:
schemas:
BenefitOffer:
additionalProperties: false
example:
benefit_group:
id: 54297cfd-cf60-4cf4-a70f-ac2061d72b44
name: Health
policy_end_date: '2024-12-31'
policy_start_date: '2024-01-01'
benefit_tier:
description: This is the premium tier for 2023 that includes medical, dental and vision benefits.
id: 66297cfd-cf60-4cf4-a70f-ac2561d92b04
name: Premium 2023 (Medical, Dental and Vision)
providers:
- id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
benefits:
- costs:
employee_cost: 234
employer_cost: 44
coverage_end_date: '2025-02-28'
coverage_start_date: '2024-03-18'
id: 562977cfd-cf60-4cf4-a70f-ac2061d709088
name: benefit name
projected_costs: null
provider:
id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
status: enrolled
type: benefit type
costs:
employee_cost: 234
employer_cost: 44
properties:
benefit_group:
$ref: '#/components/schemas/BenefitGroup'
benefit_tier:
allOf:
- $ref: '#/components/schemas/BenefitTier'
example:
description: This is the premium tier for 2023 that includes medical, dental and vision benefits.
id: 66297cfd-cf60-4cf4-a70f-ac2561d92b04
name: Premium 2023 (Medical, Dental and Vision)
providers:
- id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
nullable: true
title: MaybeBenefitTier
type: object
benefits:
items:
$ref: '#/components/schemas/Benefit'
type: array
costs:
$ref: '#/components/schemas/Costs'
required:
- benefit_group
- benefit_tier
- costs
- benefits
title: BenefitOffer
type: object
BenefitOffersByEmployment:
additionalProperties: false
example:
benefit_offers:
- benefit_group:
id: 54297cfd-cf60-4cf4-a70f-ac2061d72b44
name: Health
policy_end_date: '2024-12-31'
policy_start_date: '2024-01-01'
benefit_tier:
description: This is the premium tier for 2023 that includes medical, dental and vision benefits.
id: 66297cfd-cf60-4cf4-a70f-ac2561d92b04
name: Premium 2023 (Medical, Dental and Vision)
providers:
- id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
benefits:
- costs:
employee_cost: 234
employer_cost: 44
coverage_end_date: '2025-02-28'
coverage_start_date: '2024-03-18'
id: 562977cfd-cf60-4cf4-a70f-ac2061d709088
name: benefit name
projected_costs: null
provider:
id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
status: enrolled
type: benefit type
costs:
employee_cost: 234
employer_cost: 44
costs:
employee_cost: 234
employer_cost: 44
employment:
country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
given_name: Given Name
id: 67897cfd-cf60-4cf4-a70f-ac2061d72984
name: Name
surname: Surname
properties:
benefit_offers:
items:
$ref: '#/components/schemas/BenefitOffer'
type: array
costs:
$ref: '#/components/schemas/Costs'
employment:
$ref: '#/components/schemas/BenefitOffersEmployment'
required:
- employment
- costs
- benefit_offers
title: BenefitOffersByEmployment
type: object
CountrySubdivision:
description: A subdivision of a supported country on Remote
example:
code: PT-11
name: Lisboa
subdivision_type: District
properties:
code:
description: The ISO 3166-2 subdivision code (e.g., "PT-11" for Lisboa).
type: string
name:
description: The subdivision's name (e.g., "Lisboa", "California").
type: string
subdivision_type:
description: The type of subdivision (e.g., "District", "State", "Province").
type: string
required:
- name
title: CountrySubdivision
type: object
Benefit:
additionalProperties: false
description: 'Benefits with status enrolled have their summed costs in costs.
Benefits with status offered have their summed costs in projected_costs.
Benefit-offers where the employer opted-out have benefit_tier: null in the response.
'
example:
costs:
employee_cost: 234
employer_cost: 44
coverage_end_date: '2025-02-28'
coverage_start_date: '2024-03-18'
id: 562977cfd-cf60-4cf4-a70f-ac2061d709088
name: benefit name
projected_costs: null
provider:
id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
status: enrolled
type: benefit type
properties:
costs:
$ref: '#/components/schemas/Costs'
coverage_end_date:
description: The date when benefit coverage ends (ISO 8601).
format: date
type: string
coverage_start_date:
description: The date when benefit coverage begins (ISO 8601).
format: date
type: string
id:
description: The unique identifier (UUID) of the benefit.
type: string
name:
description: The name of the benefit (e.g., "Health Insurance", "Dental Plan").
type: string
projected_costs:
$ref: '#/components/schemas/Costs'
provider:
$ref: '#/components/schemas/BenefitProvider'
status:
description: 'The enrollment status of this benefit for the employee.
- `offered`: The benefit has been offered but the employee has not yet enrolled.
- `enrolled`: The employee is actively enrolled in this benefit.
- `waived`: The employee declined or opted out of this benefit.
'
enum:
- offered
- enrolled
- waived
type: string
type:
description: The type/category of the benefit.
type: string
required:
- id
- status
- name
- type
- coverage_start_date
- coverage_end_date
- provider
- costs
- projected_costs
title: Benefit
type: object
Country:
description: A supported country on Remote
example:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
properties:
alpha_2_code:
description: The ISO 3166-1 alpha-2 country code (e.g., "PT").
type: string
code:
description: The ISO 3166-1 alpha-3 country code (e.g., "PRT"). This is the primary code used across the Remote API.
type: string
contractor_products_available:
description: Contractor product names available for this country
items:
enum:
- standard
- plus
- cor
type: string
type: array
country_subdivisions:
description: Administrative subdivisions of the country (e.g., states, provinces, districts). Null if the country has no subdivisions relevant to Remote's services.
items:
$ref: '#/components/schemas/CountrySubdivision'
nullable: true
type: array
employment_agreement_preview_available:
description: Whether an Employment Agreement preview is available for this country.
type: boolean
eor_onboarding:
description: Whether EOR (Employer of Record) onboarding is available in this country.
type: boolean
locked_benefits:
description: When benefit plan selections become locked for this country (e.g., "after_first_hire" means benefits cannot be changed after the first employee is hired).
type: string
name:
description: The country's full English name.
type: string
region:
description: The geographic region the country belongs to (e.g., "Europe", "Asia", "Americas").
type: string
subregion:
description: The geographic subregion (e.g., "Southern Europe", "Southeast Asia"). Null for some countries.
nullable: true
type: string
supported_json_schemas:
description: The list of JSON schema form names available for this country (e.g., "address_details", "contract_details"). Use these with the Show form schema endpoint to get country-specific field requirements.
items:
type: string
type: array
required:
- alpha_2_code
- code
- name
title: Country
type: object
BenefitTier:
additionalProperties: false
description: A specific coverage level within a benefit group. For example, a "Health" benefit group might have tiers like "Basic", "Standard", and "Premium", each with different coverage and providers.
example:
description: This is the premium tier for 2023 that includes medical, dental and vision benefits.
id: 66297cfd-cf60-4cf4-a70f-ac2561d92b04
name: Premium 2023 (Medical, Dental and Vision)
providers:
- id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
properties:
description:
description: A detailed description of what this tier covers, including the types of benefits included.
type: string
id:
description: The unique identifier (UUID) of the benefit tier.
type: string
name:
description: The name of this tier (e.g., "Premium 2024 (Medical, Dental and Vision)").
type: string
providers:
description: The insurance carriers or providers associated with this tier.
items:
$ref: '#/components/schemas/BenefitProvider'
type: array
required:
- id
- name
- description
- providers
title: BenefitTier
type: object
BenefitOfferByEmploymentResponse:
additionalProperties: false
example:
data:
benefit_offers_by_employment:
- benefit_offers:
- benefit_group:
id: 54297cfd-cf60-4cf4-a70f-ac2061d72b44
name: Health
policy_end_date: '2024-12-31'
policy_start_date: '2024-01-01'
benefit_tier:
description: This is the premium tier for 2023 that includes medical, dental and vision benefits.
id: 66297cfd-cf60-4cf4-a70f-ac2561d92b04
name: Premium 2023 (Medical, Dental and Vision)
providers:
- id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
benefits:
- costs:
employee_cost: 234
employer_cost: 44
coverage_end_date: '2025-02-28'
coverage_start_date: '2024-03-18'
id: 562977cfd-cf60-4cf4-a70f-ac2061d709088
name: benefit name
projected_costs: null
provider:
id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
status: enrolled
type: benefit type
costs:
employee_cost: 234
employer_cost: 44
costs:
employee_cost: 234
employer_cost: 44
employment:
country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
given_name: Given Name
id: 67897cfd-cf60-4cf4-a70f-ac2061d72984
name: Name
surname: Surname
company_id: 79297cfd-cf60-4cf4-a70f-ac2061d72a74
currency:
code: EUR
name: European Euro
slug: eur-3b840951-099f-4bd5-90b9-032f7bfe51d9
symbol: €
properties:
data:
additionalProperties: false
properties:
benefit_offers_by_employment:
items:
$ref: '#/components/schemas/BenefitOffersByEmployment'
type: array
company_id:
description: The unique identifier (UUID) of the company.
type: string
currency:
$ref: '#/components/schemas/Currency'
required:
- benefit_offers_by_employment
- company_id
- currency
type: object
required:
- data
title: BenefitOfferByEmploymentResponse
type: object
NotFoundResponse:
description: Returned when the requested resource does not exist or is not accessible with the current authentication credentials.
example:
message: '{resource} not found'
properties:
message:
description: A message indicating which resource was not found.
pattern: Not Found
type: string
title: NotFoundResponse
type: object
BenefitProvider:
additionalProperties: false
description: The insurance carrier or provider that underwrites a benefit tier. May be null if the benefit tier does not have a specific external provider assigned.
example:
id: 88297cfd-cf60-4cf4-a70f-ac2861d92b87
name: Health Provider
nullable: true
properties:
id:
description: The unique identifier (UUID) of the benefit provider.
type: string
name:
description: The name of the insurance carrier or benefit provider (e.g., "Allianz", "Bupa").
type: string
required:
- id
- name
title: BenefitProvider
type: object
Costs:
additionalProperties: false
description: The cost breakdown between employee and employer for a benefit. Amounts are in the company's billing currency, in cents.
example:
employee_cost: 234
employer_cost: 44
nullable: true
properties:
employee_cost:
description: The employee's portion of the benefit cost, in cents.
type: integer
employer_cost:
description: The employer's portion of the benefit cost, in cents.
type: integer
required:
- employee_cost
- employer_cost
title: Costs
type: object
Currency:
description: The type of money in general use in a particular country
example:
code: EUR
name: European Euro
slug: eur-3b840951-099f-4bd5-90b9-032f7bfe51d9
symbol: €
properties:
code:
type: string
name:
type: string
slug:
type: string
symbol:
type: string
required:
- code
- slug
- symbol
title: Currency
type: object
BenefitOffersEmployment:
additionalProperties: false
description: A lightweight employment representation used in benefit offer listings.
example:
country:
alpha_2_code: PT
code: PRT
contractor_products_available:
- standard
- plus
- cor
country_subdivisions:
- code: PT-06
name: Coimbra
subdivision_type: District
- code: PT-11
name: Lisboa
subdivision_type: District
employment_agreement_preview_available: true
eor_onboarding: true
locked_benefits: after_first_hire
name: Portugal
region: Europe
subregion: Southern Europe
supported_json_schemas:
- additional_documents
- address_details
- administrative_details
- employment-basic-information
- bank_account_details
- contract_details
- emergency_contact
given_name: Given Name
id: 67897cfd-cf60-4cf4-a70f-ac2061d72984
name: Name
surname: Surname
properties:
country:
$ref: '#/components/schemas/Country'
given_name:
description: The employee's given (first) name. Null if not available.
nullable: true
type: string
id:
description: The unique identifier (UUID) of the employment.
type: string
name:
description: The employee's full name.
type: string
surname:
description: The employee's surname (last name). Null if not available.
nullable: true
type: string
required:
- id
- given_name
- name
- surname
- country
title: BenefitOffersEmployment
type: object
BenefitGroup:
additionalProperties: false
description: A category of benefits (e.g., "Health", "Dental", "Life Insurance") with a defined policy period. Each group contains one or more tiers representing different coverage levels.
example:
id: 54297cfd-cf60-4cf4-a70f-ac2061d72b44
name: Health
policy_end_date: '2024-12-31'
policy_start_date: '2024-01-01'
properties:
id:
description: The unique identifier (UUID) of the benefit group.
type: string
name:
description: The name of the benefit category (e.g., "Health", "Dental", "Life Insurance").
type: string
policy_end_date:
description: The date when the policy period ends for this benefit group (ISO 8601 format). Benefits may need to be renewed after this date.
format: date
type: string
policy_start_date:
description: The date when the policy period begins for this benefit group (ISO 8601 format).
format: date
type: string
required:
- id
- name
- policy_start_date
- policy_end_date
title: BenefitGroup
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2Assertion:
description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol.
'
flows:
clientCredentials:
scopes:
address:read: address:read
address:write: address:write
bank_account:read: bank_account:read
bank_account:write: bank_account:write
document:read: document:read
document:write: document:write
emergency_contact:read: emergency_contact:read
emergency_contact:write: emergency_contact:write
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
expense:read: expense:read
incentive:read: incentive:read
payroll: payroll
payslip:read: payslip:read
personal_detail:read: personal_detail:read
personal_detail:write: personal_detail:write
time_and_attendance: time_and_attendance
timeoff:read: timeoff:read
timeoff:write: timeoff:write
timesheet:read: timesheet:read
tokenUrl: /auth/oauth2/token
x-assertionType: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
type: oauth2
OAuth2AuthorizationCode:
description: 'Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
refreshUrl: /auth/oauth2/token
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:re
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-benefit-offers-by-employment-api-openapi.yml