Remote Getting Started API
The Getting Started API from Remote — 8 operation(s) for getting started.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Getting Started API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Getting Started
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:
- Getting Started
/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:
- Getting Started
/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:
- Getting Started
/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:
- Getting Started
/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:
- Getting Started
/v1/identity/current:
get:
callbacks: {}
description: 'Shows information about the entities that can be controlled by the current auth token.
'
operationId: get_v1_identity_current
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:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityCurrentResponse'
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: []
OAuth2AuthorizationCode: []
OAuth2ClientCredentials: []
summary: Get token identity
tags:
- Getting Started
/auth/oauth2/token:
post:
callbacks: {}
description: Endpoint to exchange tokens in the Authorization Code, Assertion Flow, Client Credentials and Refresh Token flows
operationId: post_auth_oauth2_token
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2TokenParams'
description: OAuth2Token
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2Tokens'
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:
- BasicAuth: []
summary: Token
tags:
- Getting Started
/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:
- Getting Started
components:
schemas:
ClientCredentialsParams:
example:
client_id: <client_id>
grant_type: client_credentials
properties:
client_id:
description: The client id generated during registration
type: string
grant_type:
description: The Authorization flow
enum:
- client_credentials
type: string
required:
- grant_type
- client_id
title: ClientCredentialsParams
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
AuthorizationCodeParams:
example:
code: eyJhbG...xb6H0
grant_type: authorization_code
properties:
code:
description: The authorization code generated in Authorization Code flow
type: string
grant_type:
description: The Authorization flow
enum:
- authorization_code
type: string
required:
- grant_type
- code
title: AuthorizationCodeParams
type: object
RefreshTokenResponse:
allOf:
- $ref: '#/components/schemas/BaseTokenResponse'
- example:
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.cThIIoDvwdueQB468K5xDc5633seEFoqwxjF_xSJyQQ
expires_in: 7200
refresh_token: b480036a-d229-49ef-a606-7e8fba58a5eb
token_type: Bearer
properties:
refresh_token:
description: The refresh token
type: string
type: object
example:
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.cThIIoDvwdueQB468K5xDc5633seEFoqwxjF_xSJyQQ
expires_in: 7200
refresh_token: b480036a-d229-49ef-a606-7e8fba58a5eb
token_type: Bearer
title: RefreshTokenResponse
type: object
OAuth2TokenParams:
example:
code: eyJhbG...xb6H0
grant_type: authorization_code
oneOf:
- $ref: '#/components/schemas/AuthorizationCodeParams'
- $ref: '#/components/schemas/ClientCredentialsParams'
- $ref: '#/components/schemas/RefreshTokenParams'
- $ref: '#/components/schemas/AssertionTokenParams'
title: OAuth2TokenParams
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
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
IdentityCompany:
description: The company that the current authentication token is scoped to. Only present when using a company-scoped access token or customer API token.
example:
id: afe4dc8d-0c4a-41fe-9fbf-62b752524bde
name: Company
properties:
id:
description: The unique identifier (UUID) of the company. Use this ID when making subsequent API calls that require a company reference.
type: string
name:
description: The registered name of the company on the Remote platform.
type: string
required:
- name
- id
title: IdentityCompany
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:
descr
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/remote/refs/heads/main/openapi/remote-getting-started-api-openapi.yml