Remote Countries API
The Countries API from Remote — 6 operation(s) for countries.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Countries API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Countries
paths:
/v1/countries/{country_code}/contractor-contract-details:
get:
callbacks: {}
deprecated: false
description: 'Returns the contract details JSON Schema for contractors given a country
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View forms (`form:read`) | - |
'
operationId: get_v1_countries_country_code_contractor-contract-details
parameters:
- description: Country code according to ISO 3-digit alphabetic codes
example: PRT
in: path
name: country_code
required: true
schema:
type: string
- description: Employment ID
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
in: query
name: employment_id
required: false
schema:
type: string
- description: Version of the form schema
example: 1
in: query
name: json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContractorContractDetailsResponse'
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
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'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:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
summary: Show contractor contract details
tags:
- Countries
/v1/countries/{country_code}/holidays/{year}:
get:
callbacks: {}
deprecated: false
description: 'List all holidays of a country for a specific year. Optionally, it can be filtered by country subdivision.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View countries (`country:read`) | - |
'
operationId: get_v1_countries_country_code_holidays_year
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
- description: Country code according to ISO 3166-1 3-digit alphabetic codes
example: PRT
in: path
name: country_code
required: true
schema:
type: string
- description: Year for the holidays
example: '2022'
in: path
name: year
required: true
schema:
type: string
- description: Country subdivision code according to ISO 3166-2 codes
example: PT-10
in: query
name: country_subdivision_code
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/HolidaysResponse'
description: Success
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedResponse'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- country:read
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- country:read
- company_admin
- all:write
- all:read
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- country:read
- company_admin
- all:write
- all:read
summary: List all holidays of a country
tags:
- Countries
/v1/countries/{country_code}/{form}:
get:
callbacks: {}
deprecated: false
description: "Returns the json schema of a supported form. Possible form names are:\n```\n- address_details \n- administrative_details \n- bank_account_details \n- employment_basic_information \n- contractor_basic_information \n- contractor_contract_details \n- billing_address_details \n- contract_details \n- emergency_contact \n- emergency_contact_details \n- employment_document_details \n- personal_details \n- pricing_plan_details \n- company_basic_information \n- global_payroll_administrative_details \n- global_payroll_bank_account_details \n- global_payroll_basic_information \n- global_payroll_contract_details \n- global_payroll_federal_taxes \n- global_payroll_state_taxes \n- global_payroll_personal_details \n- benefit_renewal_request \n- hris_personal_details \n\n```\n\nMost forms require a company access token, as they are dependent on certain\nproperties of companies and their current employments. However, the `address_details`\nand `company_basic_information` forms can be accessed using client_credentials\nauthentication (without a company).\n\n\n\n## Scopes\n\n| Category | Read only Scope | Write only Scope (read access implicit) |\n|---|---|---|\n| Manage company resources (`company_admin`) | View forms (`form:read`) | - |\n"
operationId: get_v1_countries_country_code_form
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
- description: Country code according to ISO 3-digit alphabetic codes
example: PRT
in: path
name: country_code
required: true
schema:
type: string
- description: Name of the desired form
example: address_details
in: path
name: form
required: true
schema:
type: string
- description: Required for `contract_amendment` and `global_payroll_state_taxes` forms
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
in: query
name: employment_id
required: false
schema:
type: string
- description: Two-letter US state code. Required for `global_payroll_state_taxes` (e.g. `NY`).
example: NY
in: query
name: jurisdiction
required: false
schema:
type: string
- description: 'FOR TESTING PURPOSES ONLY: Include scheduled benefit groups.'
example: false
in: query
name: only_for_testing_include_scheduled_benefit_groups
required: false
schema:
type: boolean
- description: Skips the dynamic benefits part of the schema if set. To be used when benefits are set via its own API.
example: true
in: query
name: skip_benefits
required: false
schema:
type: boolean
- description: Version of the form schema
example: 1
in: query
name: json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CountryFormResponse'
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
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'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:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
summary: Show form schema
tags:
- Countries
/v1/countries/{country_code}/engagement-agreement-details:
get:
callbacks: {}
deprecated: false
description: 'Returns the engagement agreement details JSON Schema for a country. Only DEU country is supported for now.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View forms (`form:read`) | - |
'
operationId: get_v1_countries_country_code_engagement-agreement-details
parameters:
- description: Country code according to ISO 3-digit alphabetic codes
example: DEU
in: path
name: country_code
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EngagementAgreementDetailsResponse'
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
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'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:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
summary: Show engagement agreement details
tags:
- Countries
/v1/countries:
get:
callbacks: {}
description: 'Returns a list of all countries that are supported by Remote API alphabetically ordered.
The supported list accounts for creating employment with basic information and it does not imply fully onboarding employment via JSON Schema.
The countries present in the list are the ones where creating a company is allowed.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View countries (`country:read`) | - |
'
operationId: get_v1_countries
parameters:
- description: 'This endpoint works with any of the access tokens provided. You can use an access
token obtained through the Client Credentials flow, the Authorization Code flow, or the Refresh Token flow.
'
example: Bearer <ANY ACCESS TOKEN>
in: header
name: Authorization
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CountriesResponse'
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
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsResponse'
description: Too many requests
security:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- country:read
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- country:read
- company_admin
- all:write
- all:read
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- country:read
- company_admin
- all:write
- all:read
summary: List countries
tags:
- Countries
/v1/countries/{country_code}/legal_entity_forms/{form}:
get:
callbacks: {}
deprecated: false
description: 'Returns the json schema of a supported form. Possible form names are:
```
- administrative_details
```
Most forms require a company access token, as they are dependent on certain
properties of companies and their current employments.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage company resources (`company_admin`) | View forms (`form:read`) | - |
'
operationId: get_v1_countries_country_code_legal_entity_forms_form
parameters:
- description: Country code according to ISO 3-digit alphabetic codes
example: PRT
in: path
name: country_code
required: true
schema:
type: string
- description: Name of the desired form
example: administrative_details
in: path
name: form
required: true
schema:
type: string
- description: Product type. Default value is global_payroll.
example: global_payroll
in: query
name: product_type
required: false
schema:
default: global_payroll
enum:
- peo
- global_payroll
- e2e_payroll
type: string
- description: Legal entity id for admistrative_details of e2e payroll products in GBR
example: 663e0b79-c893-45ff-a1b2-f6dcabc098b5
in: query
name: legal_entity_id
required: false
schema:
$ref: '#/components/schemas/UuidSlug'
- description: Version of the form schema
example: 1
in: query
name: json_schema_version
required: false
schema:
default: latest
oneOf:
- description: Specific version number
minimum: 1
type: integer
- description: Use latest version
enum:
- latest
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CountryFormResponse'
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
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundResponse'
description: Not Found
'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:
- CustomerAPIToken:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
OAuth2ClientCredentials:
- https://gateway.remote.com/company.manage
- form:read
- company_admin
- all:write
- all:read
summary: Show legal entity administrative details form schema
tags:
- Countries
components:
schemas:
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
ContractorContractDetailsResponse:
description: Response for contractor contract details
example:
data:
schema:
properties:
services_and_deliverables:
description: List of projects, project descriptions and deliverables that a Contractor shall provide
maxLength: 3000
minLength: 10
title: Services and Deliverables
type: string
x-jsf-presentation:
inputType: textarea
required:
- services_and_deliverables
type: object
x-jsf-order:
- services_and_deliverables
version: 1
properties:
data:
additionalProperties: false
description: Contractor contract details response data
properties:
schema:
additionalProperties: true
description: Contract details schema object with variable fields based on country
type: object
version:
description: JSON schema version number
type: integer
required:
- version
- schema
type: object
title: ContractorContractDetailsResponse
type: object
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
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
EngagementAgreementDetailsResponse:
description: Response for engagement agreement details
example:
data:
schema:
properties:
has_business_presence:
enum:
- 'yes'
- 'no'
title: Do you currently have any business presence in Germany?
type: string
has_cba:
enum:
- 'yes'
- 'no'
title: Are your German employees covered by any collective bargaining agreement (CBA)?
type: string
has_similar_roles:
enum:
- 'yes'
- 'no'
title: Do you currently have team members in similar roles to this hire?
type: string
type: object
version: 1
properties:
data:
additionalProperties: false
description: Engagement agreement details response data
properties:
schema:
additionalProperties: true
description: Engagement agreement details schema object with variable fields based on country
type: object
version:
description: JSON schema version number
type: integer
required:
- version
- schema
type: object
title: EngagementAgreementDetailsResponse
type: object
HolidaysResponse:
description: Holidays response
example:
data:
- day: '2021-01-01'
name: New Year's Day
note: The day after New Year's Eve
observed_day: '2021-01-02'
properties:
data:
items:
$ref: '#/components/schemas/Holiday'
type: array
title: HolidaysResponse
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
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
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
CountryFormResponse:
description: Object with required and optional fields, its descriptions and suggested presentation
example:
data:
additionalProperties: false
properties:
address:
description: Your street name and house number. PO Box addresses are not supported.
maxLength: 255
title: Address
type: string
address_line_2:
description: (Optional) For example, apartment, block, or building number.
maxLength: 255
title: Address line 2
type: string
city:
description: Enter your city
maxLength: 255
title: City
type: string
postal_code:
description: Enter zip or postal code
maxLength: 255
title: Postal code
type: string
required:
- address
- city
- postal_code
type: object
properties:
data:
type: object
title: CountryFormResponse
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
CountriesResponse:
description: List of countries supported by Remote API
example:
data:
- alpha_2_code: PT
code: PRT
employment_agreement_preview_available: true
eor_onboarding: true
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:
data:
items:
$ref: '#/components/schemas/Country'
type: array
title: CountriesResponse
type: object
Holiday:
example:
day: '2021-01-01'
name: New Year's Day
note: The day after New Year's Eve
observed_day: '2021-01-02'
properties:
day:
description: Date of the holiday
format: date
type: string
name:
description: Name of the holiday
typ
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-countries-api-openapi.yml