Remote Getting Started API
The Getting Started API from Remote — 8 operation(s) for getting started.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/remote-getting-started-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Remote 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:
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
IdentityCompanyAccessTokenResponse:
description: 'Returned when the current token was obtained via the OAuth2 Authorization Code flow and is scoped to a specific company managed by an integration partner. Contains the full context: the integration''s credentials, the company being accessed, and the user who authorized access.'
example:
data:
client_id: 1pws9iw986yq1ec57h159q29l
company:
id: afe4dc8d-0c4a-41fe-9fbf-62b752524bde
name: Company
integration:
contact_email: partner_admin@example.com
display_name: Integration Display Name
name: integration_partner
user:
email: email@example.com
id: 4117f18a-5ccf-473a-b970-608b75f5fafb
name: Jane Smith
status: created
properties:
data:
properties:
client_id:
description: The OAuth2 client ID of the integration partner that obtained this token.
type: string
company:
$ref: '#/components/schemas/IdentityCompany'
integration:
$ref: '#/components/schemas/IdentityIntegration'
user:
$ref: '#/components/schemas/IdentityUser'
required:
- client_id
- company
- integration
- user
type: object
required:
- data
title: IdentityCompanyAccessTokenResponse
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
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
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
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
type: string
note:
description: Notes about the holiday
type:
- string
- 'null'
observed_day:
description: Date when the holiday is observed
format: date
type:
- string
- 'null'
required:
- name
- day
title: Holiday
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
IdentityClientCredentialsResponse:
description: Returned when the current token was obtained via the OAuth2 Client Credentials flow. Contains the integration's client ID and details, but no company or user information since client credentials tokens are not scoped to a specific company.
example:
data:
client_id: 1pws9iw986yq1ec57h159q29l
integration:
contact_email: partner_admin@example.com
display_name: Integration Display Name
name: integration_partner
properties:
data:
properties:
client_id:
description: The OAuth2 client ID used to obtain this token.
type: string
integration:
$ref: '#/components/schemas/IdentityIntegration'
required:
- client_id
- integration
type: object
required:
- data
title: IdentityClientCredentialsResponse
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
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
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, provinc
# --- 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