openapi: 3.1.0
info:
title: Remote Companies API
description: |
Create and manage companies on the Remote.com platform. Customers and
partners use this API to onboard new companies, retrieve compliance
profiles, manage company managers and departments, configure SSO, and
issue magic links for passwordless authentication.
The Companies API is the entry point for every Remote integration. A
company-scoped access token is required for nearly every other API call
in the Remote ecosystem.
version: '2026-05-22'
contact:
name: Remote API Support
url: https://support.remote.com/
termsOfService: https://remote.com/legal/terms
license:
name: Remote API Terms
url: https://developer.remote.com/docs/api-terms
x-logo:
url: https://remote.com/favicon.ico
servers:
- url: https://gateway.remote.com/v1
description: Production
- url: https://gateway.remote-sandbox.com/v1
description: Sandbox
security:
- BearerAuth: []
tags:
- name: Companies
description: Create, retrieve, and update company records
- name: Company Managers
description: Manage administrators and managers within a company
- name: Departments
description: Manage company-defined departments and org structure
- name: Compliance
description: Read compliance profiles and supported jurisdictions
- name: SSO
description: Configure SAML/OIDC single sign-on for a company
- name: Identity
description: Inspect the identity of the current access token
- name: Magic Links
description: Generate passwordless magic links for users and employees
paths:
/companies:
get:
summary: List Companies
description: List companies accessible to the current partner or customer access token.
operationId: listCompanies
tags: [Companies]
parameters:
- $ref: '#/components/parameters/PageQuery'
- $ref: '#/components/parameters/PageSizeQuery'
responses:
'200':
description: A page of companies.
content:
application/json:
schema:
$ref: '#/components/schemas/CompanyList'
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/TooManyRequests' }
post:
summary: Create A Company
description: |
Create a new company on Remote. Returns the company resource together
with a company-scoped access token that the partner/customer may use
to call subsequent endpoints on the new company's behalf.
operationId: createCompany
tags: [Companies]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CompanyCreateRequest' }
responses:
'201':
description: Company created.
content:
application/json:
schema: { $ref: '#/components/schemas/CompanyCreateResponse' }
'400': { $ref: '#/components/responses/BadRequest' }
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/TooManyRequests' }
/companies/{company_id}:
parameters:
- $ref: '#/components/parameters/CompanyIdPath'
get:
summary: Show A Company
description: Retrieve a company by id.
operationId: showCompany
tags: [Companies]
responses:
'200':
description: Company record.
content:
application/json:
schema: { $ref: '#/components/schemas/CompanyEnvelope' }
'404': { $ref: '#/components/responses/NotFound' }
patch:
summary: Update A Company
description: Update fields on an existing company.
operationId: updateCompany
tags: [Companies]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CompanyUpdateRequest' }
responses:
'200':
description: Company updated.
content:
application/json:
schema: { $ref: '#/components/schemas/CompanyEnvelope' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
/companies/{company_id}/compliance_profile:
parameters:
- $ref: '#/components/parameters/CompanyIdPath'
get:
summary: Show Company Compliance Profile
description: Returns the compliance profile for the company including hiring eligibility signals.
operationId: showCompanyComplianceProfile
tags: [Compliance]
responses:
'200':
description: Compliance profile.
content:
application/json:
schema: { $ref: '#/components/schemas/ComplianceProfile' }
/companies/{company_id}/employment_onboarding_reserves_status:
parameters:
- $ref: '#/components/parameters/CompanyIdPath'
get:
summary: Show Employment Onboarding Reserves Status
description: Inspect the reserve payment status used to gate new EOR hires for the company.
operationId: showOnboardingReservesStatus
tags: [Compliance]
responses:
'200':
description: Reserves status.
content:
application/json:
schema: { $ref: '#/components/schemas/ReservesStatus' }
/companies/{company_id}/legal_entities:
parameters:
- $ref: '#/components/parameters/CompanyIdPath'
get:
summary: List Company Legal Entities
description: List the legal entities under which the company hires.
operationId: listCompanyLegalEntities
tags: [Companies]
responses:
'200':
description: Legal entities.
content:
application/json:
schema: { $ref: '#/components/schemas/LegalEntityList' }
/companies/{company_id}/managers:
parameters:
- $ref: '#/components/parameters/CompanyIdPath'
get:
summary: List Company Managers
operationId: listCompanyManagers
tags: [Company Managers]
responses:
'200':
description: Managers list.
content:
application/json:
schema: { $ref: '#/components/schemas/ManagerList' }
post:
summary: Create A Company Manager
operationId: createCompanyManager
tags: [Company Managers]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ManagerCreateRequest' }
responses:
'201':
description: Manager created.
content:
application/json:
schema: { $ref: '#/components/schemas/ManagerEnvelope' }
/companies/{company_id}/managers/{manager_id}:
parameters:
- $ref: '#/components/parameters/CompanyIdPath'
- $ref: '#/components/parameters/ManagerIdPath'
get:
summary: Show A Company Manager
operationId: showCompanyManager
tags: [Company Managers]
responses:
'200':
description: Manager record.
content:
application/json:
schema: { $ref: '#/components/schemas/ManagerEnvelope' }
delete:
summary: Delete A Company Manager
operationId: deleteCompanyManager
tags: [Company Managers]
responses:
'204': { description: Manager deleted. }
/companies/{company_id}/departments:
parameters:
- $ref: '#/components/parameters/CompanyIdPath'
get:
summary: List Departments
operationId: listDepartments
tags: [Departments]
responses:
'200':
description: Departments.
content:
application/json:
schema: { $ref: '#/components/schemas/DepartmentList' }
post:
summary: Create A Department
operationId: createDepartment
tags: [Departments]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/DepartmentCreateRequest' }
responses:
'201':
description: Department created.
content:
application/json:
schema: { $ref: '#/components/schemas/DepartmentEnvelope' }
/sso_configuration:
get:
summary: Show The Current SSO Configuration
operationId: showSsoConfiguration
tags: [SSO]
responses:
'200':
description: SSO configuration.
content:
application/json:
schema: { $ref: '#/components/schemas/SsoConfiguration' }
post:
summary: Create The SSO Configuration
operationId: createSsoConfiguration
tags: [SSO]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/SsoConfiguration' }
responses:
'201':
description: SSO configured.
content:
application/json:
schema: { $ref: '#/components/schemas/SsoConfiguration' }
/sso_configuration/details:
get:
summary: Show The SSO Configuration Details
operationId: showSsoConfigurationDetails
tags: [SSO]
responses:
'200':
description: SSO details.
content:
application/json:
schema: { $ref: '#/components/schemas/SsoConfiguration' }
/identity:
get:
summary: Get Token Identity
description: Shows the entities controllable by the current access token.
operationId: getTokenIdentity
tags: [Identity]
responses:
'200':
description: Identity.
content:
application/json:
schema: { $ref: '#/components/schemas/Identity' }
/magic_links:
post:
summary: Generate A Magic Link
description: |
Generate a single-use magic link to log a user (`user_id`) or
employee (`employment_id`) into Remote without a password.
operationId: generateMagicLink
tags: [Magic Links]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/MagicLinkRequest' }
responses:
'201':
description: Magic link.
content:
application/json:
schema: { $ref: '#/components/schemas/MagicLinkResponse' }
/forms/{form_type}:
parameters:
- name: form_type
in: path
required: true
schema:
type: string
enum: [company, employment, contract_amendment, benefit_offer, benefit_renewal_request, offboarding, expense]
get:
summary: Show A JSON Schema Form
description: Returns the JSON Schema form definition used by Remote to collect localized data for the given resource type.
operationId: showSchemaForm
tags: [Companies]
responses:
'200':
description: JSON Schema form.
content:
application/json:
schema:
type: object
additionalProperties: true
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Company-scoped or partner-scoped OAuth 2.0 access token.
parameters:
CompanyIdPath:
name: company_id
in: path
required: true
schema: { type: string, format: uuid }
ManagerIdPath:
name: manager_id
in: path
required: true
schema: { type: string, format: uuid }
PageQuery:
name: page
in: query
schema: { type: integer, minimum: 1, default: 1 }
PageSizeQuery:
name: page_size
in: query
schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
responses:
BadRequest:
description: Bad Request
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorResponse' }
Unauthorized:
description: Unauthorized
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorResponse' }
NotFound:
description: Not Found
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorResponse' }
TooManyRequests:
description: Too Many Requests
headers:
x-ratelimit-count:
schema: { type: integer }
description: Requests made in the current 60-second window.
x-ratelimit-remaining:
schema: { type: integer }
description: Requests remaining in the current window.
x-ratelimit-reset:
schema: { type: integer }
description: Milliseconds until the rate limit resets.
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorResponse' }
schemas:
ErrorResponse:
type: object
required: [errors]
properties:
errors:
type: object
additionalProperties: true
message:
type: string
Address:
type: object
properties:
address: { type: string }
address_line_2: { type: string }
city: { type: string }
country_code: { type: string, description: ISO 3166-1 alpha-3 country code. }
local_details: { type: object, additionalProperties: true }
postal_code: { type: string }
Company:
type: object
required: [id, name, status]
properties:
id: { type: string, format: uuid }
name: { type: string }
slug: { type: string }
external_id: { type: string, nullable: true }
status:
type: string
enum: [created, draft, profile_completed, activation_pending, activated, archived]
company_owner_user_id: { type: string, format: uuid }
primary_billing_contact: { type: string, nullable: true }
bank_account_currency_code: { type: string }
tax_number: { type: string, nullable: true }
address: { $ref: '#/components/schemas/Address' }
created_at: { type: string, format: date-time }
updated_at: { type: string, format: date-time }
CompanyEnvelope:
type: object
properties:
data:
type: object
properties:
company: { $ref: '#/components/schemas/Company' }
CompanyList:
type: object
properties:
data:
type: object
properties:
companies:
type: array
items: { $ref: '#/components/schemas/Company' }
current_page: { type: integer }
total_count: { type: integer }
total_pages: { type: integer }
CompanyCreateRequest:
type: object
required: [name, company_owner_email]
properties:
name: { type: string }
company_owner_email: { type: string, format: email }
company_owner_name: { type: string }
desired_currency: { type: string, default: USD }
external_id: { type: string }
terms_of_service_accepted_at: { type: string, format: date-time }
CompanyCreateResponse:
type: object
properties:
data:
type: object
properties:
company: { $ref: '#/components/schemas/Company' }
access_token: { type: string, description: Company-scoped access token. }
refresh_token: { type: string }
expires_in: { type: integer }
CompanyUpdateRequest:
type: object
properties:
name: { type: string }
external_id: { type: string }
address: { $ref: '#/components/schemas/Address' }
tax_number: { type: string }
ComplianceProfile:
type: object
properties:
data:
type: object
properties:
hiring_eligibility_state:
type: string
enum: [pending, additional_information_required, referred, verified, denied]
reserves_required: { type: boolean }
sanctioned_countries:
type: array
items: { type: string }
ReservesStatus:
type: object
properties:
data:
type: object
properties:
reserve_payment_required: { type: boolean }
reserve_amount: { type: integer, description: Amount in the smallest currency unit. }
reserve_currency: { type: string }
status:
type: string
enum: [not_required, requested, paid, waived]
LegalEntity:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
country_code: { type: string }
type:
type: string
enum: [remote_entity, partner_entity, customer_entity]
LegalEntityList:
type: object
properties:
data:
type: object
properties:
legal_entities:
type: array
items: { $ref: '#/components/schemas/LegalEntity' }
Manager:
type: object
required: [id, email, role]
properties:
id: { type: string, format: uuid }
email: { type: string, format: email }
name: { type: string }
role:
type: string
enum: [admin, manager, people_manager, finance_admin, owner]
status:
type: string
enum: [invited, active, deactivated]
ManagerCreateRequest:
type: object
required: [email, role]
properties:
email: { type: string, format: email }
name: { type: string }
role:
type: string
enum: [admin, manager, people_manager, finance_admin]
ManagerEnvelope:
type: object
properties:
data:
type: object
properties:
manager: { $ref: '#/components/schemas/Manager' }
ManagerList:
type: object
properties:
data:
type: object
properties:
company_managers:
type: array
items: { $ref: '#/components/schemas/Manager' }
Department:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
parent_department_id: { type: string, format: uuid, nullable: true }
DepartmentCreateRequest:
type: object
required: [name]
properties:
name: { type: string }
parent_department_id: { type: string, format: uuid }
DepartmentEnvelope:
type: object
properties:
data:
type: object
properties:
department: { $ref: '#/components/schemas/Department' }
DepartmentList:
type: object
properties:
data:
type: object
properties:
departments:
type: array
items: { $ref: '#/components/schemas/Department' }
SsoConfiguration:
type: object
properties:
data:
type: object
properties:
provider:
type: string
enum: [saml, oidc]
sso_url: { type: string, format: uri }
issuer: { type: string }
x509_certificate: { type: string }
enabled: { type: boolean }
Identity:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum: [company, partner, employment, user]
company_id: { type: string, format: uuid }
partner_id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
user_id: { type: string, format: uuid }
scopes:
type: array
items: { type: string }
MagicLinkRequest:
type: object
properties:
user_id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
timeout_in_minutes:
type: integer
minimum: 1
maximum: 1440
default: 15
target_section:
type: string
description: Optional Remote UI section to deep-link to.
MagicLinkResponse:
type: object
properties:
data:
type: object
properties:
magic_link:
type: string
format: uri
expires_at: { type: string, format: date-time }