---
updatedAt: 2026-05-27T21:29:34.000Z
agentTools:
projectIndex: https://developer.remote.com/llms.txt
---
# Creates a Benefit Renewal Request
Creates a Benefit Renewal Request for a specific Benefit Group.
This endpoint is only available in Sandbox, otherwise it will respond with a 404.
## Authentication
This endpoint accepts any one of the following token types:
- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).
# OpenAPI definition
```json
{
"components": {
"schemas": {
"DateTime": {
"description": "UTC date time in YYYY-MM-DDTHH:mm:ss format",
"example": "2021-07-15T18:18:17",
"format": "datetime",
"title": "DateTime",
"type": "string"
},
"ActionError": {
"properties": {
"action": {
"description": "The action that lead to the error message.",
"type": "string"
},
"code": {
"description": "An error code that describes the nature of the error.",
"type": "string"
},
"message": {
"description": "A developer friendly error message that gives details on what the error was and how it may be remedied.",
"type": "string"
}
},
"required": [
"code",
"message",
"action"
],
"title": "ActionError",
"type": "object"
},
"BenefitRenewalRequests.BenefitRenewalRequest": {
"additionalProperties": false,
"example": {
"benefit_group": {
"country_code": "FRA",
"id": "03b20f23-06b2-4fe2-8f21-49b445ccc1bb",
"name": "Health"
},
"benefit_renewal_response": {
"benefit_tier": {
"description": "A tier for testing purposes",
"display_cost": "~$100",
"id": "163d8f6c-2440-4f45-918b-d095f9e0ef79",
"name": "Premium"
},
"updated_at": "2021-07-01T00:00:00Z"
},
"coverage_end_date": "2022-07-01",
"coverage_start_date": "2021-07-01",
"current_benefit_tier": {
"description": "A tier for testing purposes",
"display_cost": "~$100",
"id": "163d8f6c-2440-4f45-918b-d095f9e0ef79",
"name": "Premium"
},
"id": "0073f4b5-b669-4b4a-b963-2a477f4e75a1",
"number_of_affected_employees": 10,
"renewal_selection_end_date": "2021-05-01",
"renewal_selection_instructions": "We are delighted to announce our new Global Life Insurance plans, now available in 66 countries.\nThis addition is set to significantly enhance the benefits package for your international team.\nSelection Deadline: Review and choose the right Global Life Insurance plan for each country where your team is based by 11:59 PM on December 31, 2023.\nWe offer flexible coverage options from $50,000 to $600,000, so take your time to decide what's best for your team.\nIf you don't make a selection within this period, your team members won't be enrolled in the Global Life Insurance.\nIf you wish to do so anytime next year, please reach out to help@remote.com\nFor more information on how benefits work in different countries, check out our Global benefits guide.\n",
"renewal_selection_start_date": "2021-03-01"
},
"properties": {
"benefit_group": {
"$ref": "#/components/schemas/BenefitRenewalRequests.MinimalBenefitGroup"
},
"benefit_renewal_response": {
"allOf": [
{
"$ref": "#/components/schemas/BenefitRenewalRequests.MinimalBenefitRenewalResponse"
}
],
"example": {
"benefit_tier": {
"description": "A tier for testing purposes",
"display_cost": "~$100",
"id": "163d8f6c-2440-4f45-918b-d095f9e0ef79",
"name": "Premium"
},
"updated_at": "2021-07-01T00:00:00Z"
},
"nullable": true,
"title": "MaybeBenefitRenewalRequests.MinimalBenefitRenewalResponse",
"type": "object"
},
"coverage_end_date": {
"$ref": "#/components/schemas/Date"
},
"coverage_start_date": {
"$ref": "#/components/schemas/Date"
},
"current_benefit_tier": {
"$ref": "#/components/schemas/NullableMinimalBenefitTier"
},
"id": {
"description": "The unique identifier (UUID) of the benefit renewal request.",
"type": "string"
},
"number_of_affected_employees": {
"description": "The number of employees who will be affected by this benefit renewal.",
"type": "integer"
},
"renewal_selection_end_date": {
"$ref": "#/components/schemas/Date"
},
"renewal_selection_instructions": {
"description": "Instructions for the employer about the renewal process, available plans, and deadlines.",
"type": "string"
},
"renewal_selection_start_date": {
"$ref": "#/components/schemas/Date"
}
},
"required": [
"id",
"coverage_start_date",
"coverage_end_date",
"renewal_selection_start_date",
"renewal_selection_end_date",
"renewal_selection_instructions",
"benefit_group",
"benefit_renewal_response",
"number_of_affected_employees"
],
"title": "BenefitRenewalRequests.BenefitRenewalRequest",
"type": "object"
},
"NullableMinimalBenefitTier": {
"additionalProperties": false,
"example": {
"description": "A tier for testing purposes",
"display_cost": "~$100",
"id": "163d8f6c-2440-4f45-918b-d095f9e0ef79",
"name": "Premium"
},
"nullable": true,
"properties": {
"description": {
"description": "A description of what this tier includes.",
"type": "string"
},
"display_cost": {
"description": "A human-readable cost estimate for this tier (e.g., \"~$100\"). Null if cost is not available.",
"nullable": true,
"type": "string"
},
"id": {
"description": "The unique identifier (UUID) of the benefit tier.",
"type": "string"
},
"name": {
"description": "The name of the benefit tier (e.g., \"Premium\", \"Standard\").",
"type": "string"
}
},
"required": [
"id",
"name",
"description"
],
"title": "NullableMinimalBenefitTier",
"type": "object"
},
"UnprocessableEntityResponse": {
"anyOf": [
{
"properties": {
"errors": {
"type": "object"
}
},
"required": [
"errors"
],
"type": "object"
},
{
"properties": {
"message": {
"oneOf": [
{
"type": "string"
},
{
"$ref": "#/components/schemas/ParameterError"
},
{
"items": {
"$ref": "#/components/schemas/ParameterError"
},
"title": "ParameterErrors",
"type": "array"
},
{
"$ref": "#/components/schemas/ActionError"
},
{
"items": {
"$ref": "#/components/schemas/ActionError"
},
"title": "ActionErrors",
"type": "array"
}
]
}
},
"required": [
"message"
],
"type": "object"
}
],
"example": {
"errors": {
"some_field": [
"is invalid"
]
}
},
"title": "UnprocessableEntityResponse",
"type": "object"
},
"BenefitRenewalRequests.MinimalBenefitGroup": {
"additionalProperties": false,
"description": "A lightweight benefit group reference used in renewal requests.",
"example": {
"country_code": "FRA",
"id": "03b20f23-06b2-4fe2-8f21-49b445ccc1bb",
"name": "Health"
},
"properties": {
"country_code": {
"description": "The ISO 3166-1 3-letter country code for this benefit group.",
"type": "string"
},
"id": {
"description": "The unique identifier (UUID) of the benefit group.",
"type": "string"
},
"name": {
"description": "The name of the benefit group (e.g., \"Health\", \"Life Insurance\").",
"type": "string"
}
},
"required": [
"id",
"name",
"country_code"
],
"title": "BenefitRenewalRequests.MinimalBenefitGroup",
"type": "object"
},
"BenefitRenewalRequests.MinimalBenefitRenewalResponse": {
"additionalProperties": false,
"example": {
"benefit_tier": {
"description": "A tier for testing purposes",
"display_cost": "~$100",
"id": "163d8f6c-2440-4f45-918b-d095f9e0ef79",
"name": "Premium"
},
"updated_at": "2021-07-01T00:00:00Z"
},
"properties": {
"benefit_tier": {
"$ref": "#/components/schemas/NullableMinimalBenefitTier"
},
"updated_at": {
"$ref": "#/components/schemas/DateTime"
}
},
"required": [
"benefit_tier",
"updated_at"
],
"title": "BenefitRenewalRequests.MinimalBenefitRenewalResponse",
"type": "object"
},
"TooManyRequestsResponse": {
"description": "Returned when the API rate limit has been exceeded (HTTP 429). Wait before retrying. Check the `Retry-After` response header for the recommended wait time.",
"example": {
"message": "Too many requests"
},
"properties": {
"message": {
"pattern": "Too many requests",
"type": "string"
}
},
"title": "TooManyRequestsResponse",
"type": "object"
},
"BadRequestResponse": {
"description": "Returned when the request is malformed or contains invalid parameters. The message may be a simple string or a structured object with a code and detailed message.",
"example": {
"message": "invalid {resource}"
},
"oneOf": [
{
"properties": {
"message": {
"description": "A human-readable error message describing what was wrong with the request.",
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
{
"properties": {
"message": {
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
}
},
"type": "object"
}
],
"title": "BadRequestResponse",
"type": "object"
},
"UnauthorizedResponse": {
"description": "Returned when the request does not include valid authentication credentials. Ensure you are passing a valid OAuth2 access token or API token in the Authorization header.",
"example": {
"message": "Unauthorized"
},
"properties": {
"message": {
"pattern": "Unauthorized",
"type": "string"
}
},
"required": [
"message"
],
"title": "UnauthorizedResponse",
"type": "object"
},
"Date": {
"description": "UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format",
"example": "2021-07-01",
"format": "date",
"title": "Date",
"type": "string"
},
"ParameterError": {
"example": {
"code": "invalid_param",
"message": "Invalid parameter",
"param": "employment_id"
},
"properties": {
"code": {
"description": "An error code that describes the nature of the error.",
"type": "string"
},
"message": {
"description": "A developer friendly error message that gives details on what the error was and how it may be remedied.",
"type": "string"
},
"param": {
"description": "The parameter that lead to the error message.",
"type": "string"
}
},
"required": [
"code",
"message",
"param"
],
"title": "ParameterError",
"type": "object"
},
"BenefitRenewalRequests.CreateBenefitRenewalRequest": {
"additionalProperties": false,
"description": "Benefit Renewal Request Form",
"example": {
"benefit_group_id": "03b20f23-06b2-4fe2-8f21-49b445ccc1bb"
},
"properties": {
"benefit_group_id": {
"description": "The unique identifier (UUID) of the benefit group to create a renewal request for.",
"type": "string"
}
},
"required": [
"benefit_group_id"
],
"title": "BenefitRenewalRequests.CreateBenefitRenewalRequest",
"type": "object"
},
"BenefitRenewalRequests.CreateBenefitRenewalRequestResponse": {
"additionalProperties": false,
"description": "Create Benefit Renewal Request Response",
"example": {
"data": {
"benefit_renewal_request": {
"benefit_group": {
"country_code": "FRA",
"id": "03b20f23-06b2-4fe2-8f21-49b445ccc1bb",
"name": "Health"
},
"benefit_renewal_response": {
"benefit_tier": {
"description": "A tier for testing purposes",
"display_cost": "~$100",
"id": "163d8f6c-2440-4f45-918b-d095f9e0ef79",
"name": "Premium"
},
"updated_at": "2021-07-01T00:00:00Z"
},
"coverage_end_date": "2022-07-01",
"coverage_start_date": "2021-07-01",
"current_benefit_tier": {
"description": "A tier for testing purposes",
"display_cost": "~$100",
"id": "163d8f6c-2440-4f45-918b-d095f9e0ef79",
"name": "Premium"
},
"id": "0073f4b5-b669-4b4a-b963-2a477f4e75a1",
"number_of_affected_employees": 10,
"renewal_selection_end_date": "2021-05-01",
"renewal_selection_instructions": "We are delighted to announce our new Global Life Insurance plans, now available in 66 countries.\nThis addition is set to significantly enhance the benefits package for your international team.\nSelection Deadline: Review and choose the right Global Life Insurance plan for each country where your team is based by 11:59 PM on December 31, 2023.\nWe offer flexible coverage options from $50,000 to $600,000, so take your time to decide what's best for your team.\nIf you don't make a selection within this period, your team members won't be enrolled in the Global Life Insurance.\nIf you wish to do so anytime next year, please reach out to help@remote.com\nFor more information on how benefits work in different countries, check out our Global benefits guide.\n",
"renewal_selection_start_date": "2021-03-01"
}
}
},
"properties": {
"data": {
"additionalProperties": false,
"properties": {
"benefit_renewal_request": {
"$ref": "#/components/schemas/BenefitRenewalRequests.BenefitRenewalRequest"
}
},
"required": [
"benefit_renewal_request"
],
"type": "object"
}
},
"required": [
"data"
],
"title": "BenefitRenewalRequests.CreateBenefitRenewalRequestResponse",
"type": "object"
}
},
"securitySchemes": {
"CustomerAPIToken": {
"description": "Authenticate using API Key generated by the customer in their Integration Settings page.\n",
"scheme": "bearer",
"type": "http"
},
"OAuth2": {
"description": "Authenticate using OAuth 2.0 protocol.\n",
"flows": {
"authorizationCode": {
"authorizationUrl": "/auth/oauth2/authorize",
"scopes": {
"company_department:read": "View departments: Read and list company departments",
"webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks",
"magic_link:write": "Create magic links: Create magic links",
"offboarding:write": "Manage offboarding: Creates offboarding requests",
"custom_field:write": "Manage custom fields: Create custom fields",
"address:write": "Manage addresses: Create and update employee residential address",
"expense:read": "View expenses: List and read expenses",
"employment:write": "Manage employments: Create and update employments",
"identity_verification:write": "Manage identity verification: Write identity verification data",
"timesheet:write": "Manage timesheets: Create timesheets",
"travel_letter:write": "Manage travel letters: Create travel letters",
"all:read": "Read only: List and retrieve information about all resources",
"incentive:read": "View incentives: List incentives and recurring incentives",
"personal_detail:read": "View personal details: Read employee personal information",
"invoices:write": "Manage invoices: Create invoices",
"work_authorization:write": "Manage work authorizations: Create work authorization requests",
"timeoff:write": "Manage timeoffs: Create, update and cancel timeoffs",
"company_structure:read": "View company structure: Show company structure",
"benefit_renewal:write": "Manage benefit renewals: Update benefit renewal requests",
"benefit_offer:read": "View benefit offers: List benefit offers",
"employment_documents": "Manage employment documents: Manage employment documents",
"onboarding:write": "Manage onboarding: Cancel onboarding",
"https://gateway.remote.com/company.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file",
"project:write": "Manage projects: Create and update company projects and their leads and team members",
"pay_in_details:read": "View pay-in details: Read the payment reference and Remote's bank details for paying contractor invoices",
"payroll_run:read": "View payroll runs: List and show payroll runs",
"risk_reserve:write": "Manage risk reserves: Create risk reserves for a company",
"invoices": "Manage invoices: Manage invoices",
"resignation_letter:read": "View resignation letters: Read resignation letters",
"resignation:read": "View resignations: Read resignation requests",
"convert_currency:read": "Convert currencies: Convert currencies",
"all:write": "Full Access: Grant access to all scopes based on your current role permissions",
"https://gateway.remote.com/employment.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file",
"employments": "Manage employments: Create and manage employments",
"probation_document:read": "View probation documents: Read probation completion letters and probation extensions documents",
"company_admin": "Manage company resources: Create and manage company resources",
"payroll": "Manage payroll runs: Manage payroll runs and calendars",
"help_center_article:read": "View help articles: Read help center articles",
"timesheet:read": "View timesheets: Read timesheets",
"custom_field_value:write": "Manage custom field values: Create custom field values",
"company_currencies:read": "View company currencies: List company supported currencies",
"payslip:read": "View payslips: List and show employee's payslip",
"pay_item:write": "Manage pay items: Create pay items for employments",
"resignation:write": "Manage resignations: Validate resignation requests",
"custom_field:read": "View custom fields: List custom fields",
"payroll_calendar:read": "View payroll calendars: List payroll calendars",
"contract_amendment:write": "Manage contract amendments: Create contract amendments",
"offboarding:read": "View offboarding requests: Read and list offboarding requests",
"timeoff:read": "View timeoffs: Read and list timeoffs",
"pay_in_details": "View pay-in bank details: Read the payment reference and Remote's receiving bank accounts for paying invoices",
"probation_document:write": "Manage probation documents: Create probation completion letters and probation extensions documents",
"country:read": "View countries: Read and list countries",
"webhook:read": "View webhooks: Read webhooks callback logs",
"company_department:write": "Manage departments: Create company departments",
"company_manager:read": "View managers: Read and list company managers",
"pay_item:read": "View pay items: List pay items for employments",
"contract_amendment:read": "View contract amendments: List and show contract amendments",
"company:read": "View companies: Read and list companies",
"sso_configuration:write": "Manage SSO: Set SSO configuration",
"benefit_offer:write": "Manage benefit offers: Create benefit offers",
"contract_eligibility:write": "Manage contract eligibility: Create contract eligibility for an employment",
"benefit_renewal:read": "View benefit renewals: List benefit renewal requests",
"background_check:read": "View background checks: Read and show background check requests",
"custom_field_value:read": "View custom field values: List custom field values",
"expense:write": "Manage expenses: Create expenses",
"identity_verification:read": "View identity verification: Read identity verification data",
"address:read": "View addresses: Read employee residential address",
"document:write": "Manage documents: Write and update documents",
"time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets",
"employment_payments": "Manage expenses: Manage expenses and incentives",
"form:read": "View forms: Read json schema forms",
"work_authorization:read": "View work authorizations: List work authorization requests",
"invoices:read": "View invoices: Read and list invoices",
"incentive:write": "Manage incentives: Create incentives",
"employment:read": "View employments: List and read employments",
"contract:read": "View contracts: List employment contracts",
"projects": "Manage projects: Create and manage company projects and their leads and team members",
"company_manager:write": "Manage managers: Create and delete company managers",
"travel_letter:read": "View travel letters: Read travel letters",
"project:read": "View projects: List and read company projects",
"document:read": "View documents: Read and list documents",
"sso_configuration:read": "View SSO configuration: Read SSO configuration"
},
"tokenUrl": "/auth/oauth2/token"
},
"clientCredentials": {
"scopes": {
"all:read": "Read only: List and retrieve information about all resources",
"all:write": "Full Access: Grant access to all scopes based on your current role permissions",
"company:read": "View companies: Read and list companies",
"company:write": "Manage companies: Create, Read and update companies",
"company_admin": "Manage company resources: Create and manage company resources",
"company_management": "Manage companies: Create and manage companies",
"convert_currency:read": "Convert currencies: Convert currencies",
"country:read": "View countries: Read and list countries",
"employment_documents": "Manage employment documents: Manage employment documents",
"employment_payments": "Manage expenses: Manage expenses and incentives",
"employments": "Manage employments: Create and manage employments",
"help_center_article:read": "View help articles: Read help center articles",
"https://gateway.remote.com/company.manage": "Legacy scope, kept as sent. Some endpoints accept it, not all: see the endpoint's `security` in the OpenAPI file",
"https://gateway.remote.com/employment.manage": "Legacy scope, kept as sent. Some endpoints accept it, not all: see the endpoint's `security` in the OpenAPI file",
"invoices": "Manage invoices: Manage invoices",
"payroll": "Manage payroll runs: Manage payroll runs and calendars",
"payroll_calendar:read": "View payroll calendars: List payroll calendars",
"pricing_plan:read": "View pricing plans: List pricing plans",
"pricing_plan:write": "Manage pricing plans: Create pricing plans",
"time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets",
"webhook:read": "View webhooks: Read webhooks callback logs",
"webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks"
},
"tokenUrl": "/auth/oauth2/token"
}
},
"type": "oauth2"
},
"OAuth2AuthorizationCode": {
"description": "Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.\n",
"flows": {
"authorizationCode": {
"authorizationUrl": "/auth/oauth2/authorize",
"refreshUrl": "/auth/oauth2/token",
"scopes": {
"company_department:read": "View departments: Read and list company departments",
"webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks",
"magic_link:write": "Create magic links: Create magic links",
"offboarding:write": "Manage offboarding: Creates offboarding requests",
"custom_field:write": "Manage custom fields: Create custom fields",
"address:write": "Manage addresses: Create and update employee residential address",
"expense:read": "View expenses: List and read expenses",
"employment:write": "Manage employments: Create and update employments",
"identity_verification:write": "Manage identity verification: Write identity verification data",
"timesheet:write": "Manage timesheets: Create timesheets",
"travel_letter:write": "Manage travel letters: Create travel letters",
"all:read": "Read only: List and retrieve information about all resources",
"incentive:read": "View incentives: List incentives and recurring incentives",
"personal_detail:read": "View personal details: Read employee personal information",
"invoices:write": "Manage invoices: Create invoices",
"work_authorization:write": "Manage work authorizations: Create work authorization requests",
"timeoff:write": "Manage timeoffs: Create, update and cancel timeoffs",
"company_structure:read": "View company structure: Show company structure",
"benefit_renewal:write": "Manage benefit renewals: Update benefit renewal requests",
"benefit_offer:read": "View benefit offers: List benefit offers",
"employment_documents": "Manage employment documents: Manage employment documents",
"onboarding:write": "Manage onboarding: Cancel onboarding",
"https://gateway.remote.com/company.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file",
"project:write": "Manage projects: Create and update company projects and their leads and team members",
"pay_in_details:read": "View pay-in details: Read the payment reference and Remote's bank details for paying contractor invoices",
"payroll_run:read": "View payroll runs: List and show payroll runs",
"risk_reserve:write": "Manage risk reserves: Create risk reserves for a company",
"invoices": "Manage invoices: Manage invoices",
"resignation_letter:read": "View resignation letters: Read resignation letters",
"resignation:read": "View resignations: Read resignation requests",
"convert_currency:read": "Convert currencies: Convert currencies",
"all:write": "Full Access: Grant access to all scopes based on your current role permissions",
"https://gateway.remote.com/employment.manage": "Legacy scope. A new request for it gets `all:write`; tokens authorized before late March 2026 may still hold it. Many endpoints accept it, but not all: see the endpoint's `security` in the OpenAPI file",
"employments": "Manage employments: Create and manage employments",
"probation_document:read": "View probation documents: Read probation completion letters and probation extensions documents",
"company_admin": "Manage company resources: Create and manage company resources",
"payroll": "Manage payroll runs: Manage payroll runs and calendars",
"help_center_article:read": "View help articles: Read help center articles",
"timesheet:read": "View timesheets: Read timesheets",
"custom_field_value:write": "Manage custom field values: Create custom field values",
"company_currencies:read": "View company currencies: List company supported currencies",
"payslip:read": "View payslips: List and show employee's payslip",
"pay_item:write": "Manage pay items: Create pay items for employments",
"resignation:write": "Manage resignations: Validate resignation requests",
"custom_field:read": "View custom fields: List custom fields",
"payroll_calendar:read": "View payroll calendars: List payroll calendars",
"contract_amendment:write": "Manage contract amendments: Create contract amendments",
"offboarding:read": "View offboarding requests: Read and list offboarding requests",
"timeoff:read": "View timeoffs: Read and list timeoffs",
"pay_in_details": "View pay-in bank details: Read the payment reference and Remote's receiving bank accounts for paying invoices",
"probation_document:write": "Manage probation documents: Create probation completion letters and probation extensions documents",
"country:read": "View countries: Read and list countries",
"webhook:read": "View webhooks: Read webhooks callback logs",
"company_department:write": "Manage departments: Create company departments",
"company_manager:read": "View managers: Read and list company managers",
"pay_item:read": "View pay items: List pay items for employments",
"contract_amendment:read": "View contract amendments: List and show contract amendments",
"company:read": "View companies: Read and list companies",
"sso_configuration:write": "Manage SSO: Set SSO configuration",
"benefit_offer:write": "Manage benefit offers: Create benefit offers",
"contract_eligibility:write": "Manage contract eligibility: Create contract eligibility for an employment",
"benefit_renewal:read": "View benefit renewals: List benefit renewal requests",
"background_check:read": "View background checks: Read and show background check requests",
"custom_field_value:read": "View custom field values: List custom field values",
"expense:write": "Manage expenses: Create expenses",
"identity_verification:read": "View identity verification: Read identity verification data",
"address:read": "View addresses: Read employee residential address",
"document:write": "Manage documents: Write and update documents",
"time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets",
"employment_payments": "Manage expenses: Manage expenses and incentives",
"form:read": "View forms: Read json schema forms",
"work_authorization:read": "View work authorizations: List work authorization requests",
"invoices:read": "View invoices: Read and list invoices",
"incentive:write": "Manage incentives: Create incentives",
"employment:read": "View employments: List and read employments",
"contract:read": "View contracts: List employment contracts",
"projects": "Manage projects: Create and manage company projects and their leads and team members",
"company_manager:write": "Manage managers: Create and delete company managers",
"travel_letter:read": "View travel letters: Read travel letters",
"project:read": "View projects: List and read company projects",
"document:read": "View documents: Read and list documents",
"sso_configuration:read": "View SSO configuration: Read SSO configuration"
},
"tokenUrl": "/auth/oauth2/token"
}
},
"type": "oauth2"
},
"OAuth2CompanyManagerAssertion": {
"description": "Authenticate as a company manager using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol,\nwith an assertion whose subject is `urn:remote-api:company-manager:user:`, where `` is the\ncompany manager's Remote `user_id`. Each user belongs to one company.\n\nOpenAPI has no flow type for this grant, so it is declared as a client credentials flow. Request the token\nfrom the token URL with this grant type and a signed assertion, not with `client_credentials`.\n\nRemote must allow the integration to act on behalf of users, and the integration must manage the user's company.\nRemote can also limit an integration to grants that carry a user's consent, such as the Authorization Code flow;\nthis grant is then refused.\n\nThe token acts as that company manager, and is accepted wherever a company manager's token from the\nAuthorization Code flow is.\n",
"flows": {
"clientCredentials": {
"scopes": {
"company_department:read": "View departments: Read and list company departments",
"webhook:write": "Manage webhooks: Set webhook callbacks and replay webhooks",
"magic_link:write": "Create magic links: Create magic links",
"offboarding:write": "Manage offboarding: Creates offboarding requests",
"custom_field:write": "Manage custom fields: Create custom fields",
"address:write": "Manage addresses: Create and update employee residential address",
"expense:read": "View expenses: List and read expenses",
"employment:write": "Manage employments: Create and update employments",
"identity_verification:write": "Manage identity verification: Write identity verification data",
"timesheet:write": "Manage timesheets: Create timesheets",
"travel_letter:write": "Manage travel letters: Create travel letters",
"all:read": "Read only: List and retrieve information about all resources",
"incentive:read": "View incentives: List incentives and recurring incentives",
"personal_detail:read": "View personal details: Read employee personal information",
"invoices:write": "Manage invoices: Create invoices",
"work_authorization:write": "Manage work authorizations: Create work authorization requests",
"timeoff:write": "Manage timeoffs: Create, update and cancel timeoffs",
"company_structure:read": "View company structure: Show company structure",
"benefit_renewal:write": "Manage benefit renewals: Update benefit renewal requests",
"benefit_offer:read": "View benefit offers: List benefit offers",
"employment_documents": "Manage employment documents: Manage employment documents",
"onboarding:write": "Manage onboarding: Cancel onboarding",
"https://gateway.remote.com/company.manage": "Legacy scope. A request that includes it gets a token with only `all:write`, so no assertion token holds it. Request `all:write` or a narrower scope instead",
"project:write": "Manage projects: Create and update company projects and their leads and team members",
"pay_in_details:read": "View pay-in details: Read the payment reference and Remote's bank details for paying contractor invoices",
"payroll_run:read": "View payroll runs: List and show payroll runs",
"risk_reserve:write": "Manage risk reserves: Create risk reserves for a company",
"invoices": "Manage invoices: Manage invoices",
"resignation_letter:read": "View resignation letters: Read resignation letters",
"resignation:read": "View resignations: Read resignation requests",
"convert_currency:read": "Convert currencies: Convert currencies",
"all:write": "Full Access: Grant access to all scopes based on your current role permissions",
"https://gateway.remote.com/employment.manage": "Legacy scope. A request that includes it gets a token with only `all:write`, so no assertion token holds it. Request `all:write` or a narrower scope instead",
"employments": "Manage employments: Create and manage employments",
"probation_document:read": "View probation documents: Read probation completion letters and probation extensions documents",
"company_admin": "Manage company resources: Create and manage company resources",
"payroll": "Manage payroll runs: Manage payroll runs and calendars",
"help_center_article:read": "View help articles: Read help center articles",
"timesheet:read": "View timesheets: Read timesheets",
"custom_field_value:write": "Manage custom field values: Create custom field values",
"company_currencies:read": "View company currencies: List company supported currencies",
"payslip:read": "View payslips: List and show employee's payslip",
"pay_item:write": "Manage pay items: Create pay items for employments",
"resignation:write": "Manage resignations: Validate resignation requests",
"custom_field:read": "View custom fields: List custom fields",
"payroll_calendar:read": "View payroll calendars: List payroll calendars",
"contract_amendment:write": "Manage contract amendments: Create contract amendments",
"offboarding:read": "View offboarding requests: Read and list offboarding requests",
"timeoff:read": "View timeoffs: Read and list timeoffs",
"pay_in_details": "View pay-in bank details: Read the payment reference and Remote's receiving bank accounts for paying invoices",
"probation_document:write": "Manage probation documents: Create probation completion letters and probation extensions documents",
"country:read": "View countries: Read and list countries",
"webhook:read": "View webhooks: Read webhooks callback logs",
"company_department:write": "Manage departments: Create company departments",
"company_manager:read": "View managers: Read and list company managers",
"pay_item:read": "View pay items: List pay items for employments",
"contract_amendment:read": "View contract amendments: List and show contract amendments",
"company:read": "View companies: Read and list companies",
"sso_configuration:write": "Manage SSO: Set SSO configuration",
"benefit_offer:write": "Manage benefit offers: Create benefit offers",
"contract_eligibility:write": "Manage contract eligibility: Create contract eligibility for an employment",
"benefit_renewal:read": "View benefit renewals: List benefit renewal requests",
"background_check:read": "View background checks: Read and show background check requests",
"custom_field_value:read": "View custom field values: List custom field values",
"expense:write": "Manage expenses: Create expenses",
"identity_verification:read": "View identity verification: Read identity verification data",
"address:read": "View addresses: Read employee residential address",
"document:write": "Manage documents: Write and update documents",
"time_and_attendance": "Manage timeoffs: Manage timeoffs, leave-policies and timesheets",
"employment_payments": "Manage expenses: Manage expenses and incentives",
"form:read": "View forms: Read json schema forms",
"work_authorization:read": "View work authorizations: List work authorization requests",
"invoices:read": "View invoices: Read and list invoices",
"incentive:write": "Manage incentives: Create incentives",
"employment:read": "View employments: List and read employments",
"contract:read": "View contracts: List employment contracts",
"projects": "Manage projects: Create and manage company projects and their leads and team members",
"company_manager:write": "Manage managers: Create and delete company managers",
"travel_letter:read": "View travel letters: Read travel letters",
"project:read": "View projects: List and read company projects",
"document:read": "View documents: Read and list documents",
"sso_configuration:read": "View SSO configuration: Read SSO configuration"
},
"tokenUrl": "/auth/oauth2/token",
"x-grantType": "urn:ietf:params:oauth:grant-type:jwt-bearer"
}
},
"type": "oauth2"
}
}
},
"info": {
"title": "Testing & Sandbox",
"version": "2.0.0"
},
"openapi": "3.1.0",
"paths": {
"/v1/sandbox/benefit-renewal-requests": {
"post": {
"callbacks": {},
"deprecated": false,
"description": "Creates a Benefit Renewal Request for a specific Benefit Group.\nThis endpoint is only available in Sandbox, otherwise it will respond with a 404.\n\n## Authentication\n\nThis endpoint accepts any one of the following token types:\n\n- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).\n- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).\n- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).",
"operationId": "post_v1_sandbox_benefit-renewal-requests",
"parameters": [
{
"description": "An access token of one of the types listed in this endpoint's Authentication section, as `Bearer `.\n\nA token from the Refresh Token flow is of the same type as the token issued with that refresh token.\n",
"example": "Bearer ACCESS_TOKEN",
"in": "header",
"name": "Authorization",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BenefitRenewalRequests.CreateBenefitRenewalRequest"
}
}
},
"description": "Benefit Renewal Request",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BenefitRenewalRequests.CreateBenefitRenewalRequestResponse"
}
}
},
"description": "Success"
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
},
"description": "Unauthorized"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnprocessableEntityResponse"
}
}
},
"description": "Unprocessable Entity"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TooManyRequestsResponse"
}
}
},
"description": "Unprocessable Entity"
}
},
"security": [
{
"OAuth2AuthorizationCode": []
},
{
"OAuth2CompanyManagerAssertion": []
},
{
"CustomerAPIToken": []
}
],
"summary": "Creates a Benefit Renewal Request",
"tags": [
"Sandbox"
]
}
}
},
"security": [
{
"OAuth2": []
}
],
"servers": [
{
"url": "https://gateway.remote.com/",
"variables": {}
},
{
"url": "https://gateway.remote-sandbox.com/",
"variables": {}
}
]
}
```