openapi: 3.1.0
info:
title: Remote Employments API
description: |
Create and manage employment records across the EOR, Global Payroll, and
PEO employment models on Remote.com. Endpoints cover the full employment
lifecycle — onboarding, contract management, contract amendments,
employment status transitions, identity verification, travel letters,
work-authorization requests, and offboarding.
Every Remote customer hiring through the platform owns one employment
record per worker. This API is the authoritative source for that record.
version: '2026-05-22'
contact:
name: Remote API Support
url: https://support.remote.com/
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: Employments
description: Create, read, update, and invite employment records
- name: Employment Contracts
description: View active and pending employment contracts
- name: Contract Amendments
description: Submit and track contract amendments
- name: Contract Documents
description: Sign, retrieve, and manage employment contract documents
- name: Onboarding
description: Drive employee onboarding flows
- name: Offboarding
description: Drive employee offboarding flows
- name: Identity Verification
description: Identity-verification background checks
- name: Travel Letters
description: Travel letter requests for employees moving across borders
- name: Work Authorization
description: Work authorization (visa / right to work) requests
- name: Company Structure
description: Reporting hierarchy and structure nodes for employees
paths:
/employments:
get:
summary: List Employments
description: List all non-deleted employments for the company, with filtering.
operationId: listEmployments
tags: [Employments]
parameters:
- { name: company_id, in: query, schema: { type: string, format: uuid } }
- { name: email, in: query, schema: { type: string, format: email } }
- { name: status, in: query, schema: { $ref: '#/components/schemas/EmploymentStatus' } }
- { name: employment_type, in: query, schema: { type: string, enum: [employee, contractor, director] } }
- { name: employment_model, in: query, schema: { type: string, enum: [global_payroll, peo, eor] } }
- { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
- { name: page_size, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
responses:
'200':
description: A page of employments.
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentList' }
'401': { $ref: '#/components/responses/Unauthorized' }
'429': { $ref: '#/components/responses/TooManyRequests' }
post:
summary: Create An Employment
description: |
Create a new employment. Required fields depend on the employment
model (EOR vs. Global Payroll vs. PEO) and the country. Use
`/forms/employment` to fetch the per-country JSON Schema form.
operationId: createEmployment
tags: [Employments]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentCreateRequest' }
responses:
'201':
description: Employment created.
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentEnvelope' }
'400': { $ref: '#/components/responses/BadRequest' }
/employments/{employment_id}:
parameters:
- $ref: '#/components/parameters/EmploymentIdPath'
get:
summary: Show An Employment
operationId: showEmployment
tags: [Employments]
responses:
'200':
description: Employment record.
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentEnvelope' }
'404': { $ref: '#/components/responses/NotFound' }
patch:
summary: Update An Employment
operationId: updateEmployment
tags: [Employments]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentUpdateRequest' }
responses:
'200':
description: Employment updated.
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentEnvelope' }
/employments/{employment_id}/invite:
parameters:
- $ref: '#/components/parameters/EmploymentIdPath'
post:
summary: Invite An Employment To Self-Serve Onboarding
operationId: inviteEmployment
tags: [Employments, Onboarding]
responses:
'202':
description: Invitation sent.
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentEnvelope' }
/employments/{employment_id}/administrative_details:
parameters:
- $ref: '#/components/parameters/EmploymentIdPath'
get:
summary: Show Administrative Details
operationId: showAdministrativeDetails
tags: [Employments]
responses:
'200':
description: Administrative details.
content:
application/json:
schema:
type: object
additionalProperties: true
put:
summary: Update Administrative Details
operationId: updateAdministrativeDetails
tags: [Employments]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Updated.
content:
application/json:
schema:
type: object
additionalProperties: true
/employments/{employment_id}/contracts:
parameters:
- $ref: '#/components/parameters/EmploymentIdPath'
get:
summary: List Employment Contracts
operationId: listEmploymentContracts
tags: [Employment Contracts]
responses:
'200':
description: Contracts.
content:
application/json:
schema: { $ref: '#/components/schemas/EmploymentContractList' }
/employments/{employment_id}/contracts/pending_changes:
parameters:
- $ref: '#/components/parameters/EmploymentIdPath'
get:
summary: Get Pending Contract Changes
operationId: getPendingContractChanges
tags: [Employment Contracts]
responses:
'200':
description: Pending changes.
content:
application/json:
schema:
type: object
additionalProperties: true
/contract_amendments:
get:
summary: List Contract Amendments
operationId: listContractAmendments
tags: [Contract Amendments]
parameters:
- { name: employment_id, in: query, schema: { type: string, format: uuid } }
- { name: status, in: query, schema: { type: string, enum: [draft, submitted, review_started, done, canceled, deleted] } }
responses:
'200':
description: Contract amendments.
content:
application/json:
schema: { $ref: '#/components/schemas/ContractAmendmentList' }
post:
summary: Create A Contract Amendment
operationId: createContractAmendment
tags: [Contract Amendments]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ContractAmendmentCreateRequest' }
responses:
'201':
description: Created.
content:
application/json:
schema: { $ref: '#/components/schemas/ContractAmendmentEnvelope' }
/contract_amendments/automatable:
post:
summary: Submit An Automatable Contract Amendment
description: |
Automatable amendments use a structured payload that Remote can
approve without manual review. Use the `/contract_amendments/schema`
endpoint to learn the per-country form requirements.
operationId: createAutomatableContractAmendment
tags: [Contract Amendments]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'201':
description: Created.
content:
application/json:
schema: { $ref: '#/components/schemas/ContractAmendmentEnvelope' }
/contract_amendments/{contract_amendment_id}:
parameters:
- { name: contract_amendment_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show A Contract Amendment
operationId: showContractAmendment
tags: [Contract Amendments]
responses:
'200':
description: Amendment.
content:
application/json:
schema: { $ref: '#/components/schemas/ContractAmendmentEnvelope' }
/contract_amendments/schema:
get:
summary: Show A Contract Amendment Schema
description: Returns the JSON Schema form definition for amendments in a given country and employment.
operationId: showContractAmendmentSchema
tags: [Contract Amendments]
parameters:
- { name: employment_id, in: query, required: true, schema: { type: string, format: uuid } }
responses:
'200':
description: JSON Schema form.
content:
application/json:
schema:
type: object
additionalProperties: true
/contract_documents:
post:
summary: Create A Contract Document
operationId: createContractDocument
tags: [Contract Documents]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'201':
description: Created.
content:
application/json:
schema: { $ref: '#/components/schemas/ContractDocumentEnvelope' }
/contract_documents/{contract_document_id}:
parameters:
- { name: contract_document_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show A Contract Document
operationId: showContractDocument
tags: [Contract Documents]
responses:
'200':
description: Contract document.
content:
application/json:
schema: { $ref: '#/components/schemas/ContractDocumentEnvelope' }
/contract_documents/{contract_document_id}/sign:
parameters:
- { name: contract_document_id, in: path, required: true, schema: { type: string, format: uuid } }
post:
summary: Sign A Contract Document
operationId: signContractDocument
tags: [Contract Documents]
responses:
'200':
description: Signed.
content:
application/json:
schema: { $ref: '#/components/schemas/ContractDocumentEnvelope' }
/employments/{employment_id}/eligibility:
parameters:
- $ref: '#/components/parameters/EmploymentIdPath'
post:
summary: Create An Eligibility Questionnaire
operationId: createEligibilityQuestionnaire
tags: [Onboarding]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'201':
description: Eligibility questionnaire created.
content:
application/json:
schema:
type: object
additionalProperties: true
/employments/{employment_id}/eligibility/{questionnaire_id}:
parameters:
- $ref: '#/components/parameters/EmploymentIdPath'
- { name: questionnaire_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show An Eligibility Questionnaire
operationId: showEligibilityQuestionnaire
tags: [Onboarding]
responses:
'200':
description: Questionnaire.
content:
application/json:
schema:
type: object
additionalProperties: true
/eor_hiring/risk_reserve/proof_of_payment:
post:
summary: Submit Risk Reserve Proof Of Payment
operationId: submitRiskReserveProofOfPayment
tags: [Onboarding]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'202':
description: Accepted.
/offboardings:
post:
summary: Submit An Offboarding
operationId: submitOffboarding
tags: [Offboarding]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/OffboardingCreateRequest' }
responses:
'201':
description: Offboarding submitted.
content:
application/json:
schema: { $ref: '#/components/schemas/OffboardingEnvelope' }
/offboardings/{offboarding_id}:
parameters:
- { name: offboarding_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show An Offboarding
operationId: showOffboarding
tags: [Offboarding]
responses:
'200':
description: Offboarding.
content:
application/json:
schema: { $ref: '#/components/schemas/OffboardingEnvelope' }
/travel_letter_requests:
get:
summary: List Travel Letter Requests
operationId: listTravelLetterRequests
tags: [Travel Letters]
responses:
'200':
description: Travel letter requests.
content:
application/json:
schema: { $ref: '#/components/schemas/TravelLetterRequestList' }
post:
summary: Create A Travel Letter Request
operationId: createTravelLetterRequest
tags: [Travel Letters]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'201':
description: Created.
content:
application/json:
schema: { $ref: '#/components/schemas/TravelLetterRequestEnvelope' }
/travel_letter_requests/{travel_letter_request_id}:
parameters:
- { name: travel_letter_request_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show A Travel Letter Request
operationId: showTravelLetterRequest
tags: [Travel Letters]
responses:
'200':
description: Travel letter request.
content:
application/json:
schema: { $ref: '#/components/schemas/TravelLetterRequestEnvelope' }
patch:
summary: Update A Travel Letter Request
operationId: updateTravelLetterRequest
tags: [Travel Letters]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Updated.
content:
application/json:
schema: { $ref: '#/components/schemas/TravelLetterRequestEnvelope' }
/work_authorization_requests:
get:
summary: List Work Authorization Requests
operationId: listWorkAuthorizationRequests
tags: [Work Authorization]
responses:
'200':
description: Work authorization requests.
content:
application/json:
schema: { $ref: '#/components/schemas/WorkAuthorizationRequestList' }
/work_authorization_requests/{work_authorization_request_id}:
parameters:
- { name: work_authorization_request_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Show A Work Authorization Request
operationId: showWorkAuthorizationRequest
tags: [Work Authorization]
responses:
'200':
description: Work authorization request.
content:
application/json:
schema: { $ref: '#/components/schemas/WorkAuthorizationRequestEnvelope' }
patch:
summary: Update A Work Authorization Request
operationId: updateWorkAuthorizationRequest
tags: [Work Authorization]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Updated.
content:
application/json:
schema: { $ref: '#/components/schemas/WorkAuthorizationRequestEnvelope' }
/company_structure_nodes:
get:
summary: List Company Structure Nodes
operationId: listCompanyStructureNodes
tags: [Company Structure]
parameters:
- { name: employment_id, in: query, schema: { type: string, format: uuid } }
responses:
'200':
description: Structure nodes.
content:
application/json:
schema:
type: object
additionalProperties: true
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
EmploymentIdPath:
name: employment_id
in: path
required: true
schema: { type: string, format: uuid }
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
content:
application/json:
schema: { $ref: '#/components/schemas/ErrorResponse' }
schemas:
ErrorResponse:
type: object
properties:
errors: { type: object, additionalProperties: true }
message: { type: string }
EmploymentStatus:
type: string
enum:
- created
- invited
- initiated
- pending
- active
- probation
- offboarding_initiated
- offboarded
- archived
EmploymentLifecycleStage:
type: string
enum:
- employment_creation
- onboarding
- reserve_invoice
- probation
- active
- offboarding
- archived
Employment:
type: object
required: [id, status, employment_type]
properties:
id: { type: string, format: uuid }
company_id: { type: string, format: uuid }
external_id: { type: string, nullable: true }
full_name: { type: string }
personal_email: { type: string, format: email }
work_email: { type: string, format: email, nullable: true }
country:
type: object
properties:
code: { type: string }
name: { type: string }
employment_type:
type: string
enum: [employee, contractor, director]
employment_model:
type: string
enum: [global_payroll, peo, eor]
status: { $ref: '#/components/schemas/EmploymentStatus' }
lifecycle_stage: { $ref: '#/components/schemas/EmploymentLifecycleStage' }
job_title: { type: string }
manager_id: { type: string, format: uuid, nullable: true }
department_id: { type: string, format: uuid, nullable: true }
start_date: { type: string, format: date }
provisional_start_date: { type: string, format: date, nullable: true }
created_at: { type: string, format: date-time }
updated_at: { type: string, format: date-time }
EmploymentList:
type: object
properties:
data:
type: object
properties:
employments:
type: array
items: { $ref: '#/components/schemas/Employment' }
current_page: { type: integer }
total_count: { type: integer }
total_pages: { type: integer }
EmploymentEnvelope:
type: object
properties:
data:
type: object
properties:
employment: { $ref: '#/components/schemas/Employment' }
EmploymentCreateRequest:
type: object
required: [full_name, country_code, personal_email, employment_type]
properties:
full_name: { type: string }
country_code: { type: string }
personal_email: { type: string, format: email }
employment_type:
type: string
enum: [employee, contractor, director]
employment_model:
type: string
enum: [global_payroll, peo, eor]
default: eor
provisional_start_date: { type: string, format: date }
job_title: { type: string }
external_id: { type: string }
invite_user: { type: boolean, default: false }
EmploymentUpdateRequest:
type: object
properties:
full_name: { type: string }
work_email: { type: string, format: email }
manager_id: { type: string, format: uuid }
department_id: { type: string, format: uuid }
job_title: { type: string }
EmploymentContract:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
status:
type: string
enum: [draft, pending_signature, active, terminated]
contract_type:
type: string
enum: [indefinite, fixed_term]
currency_code: { type: string }
annual_gross_salary: { type: integer, description: Amount in smallest currency unit. }
weekly_hours: { type: number }
EmploymentContractList:
type: object
properties:
data:
type: object
properties:
employment_contracts:
type: array
items: { $ref: '#/components/schemas/EmploymentContract' }
ContractAmendment:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
status:
type: string
enum: [draft, submitted, review_started, done, canceled, deleted]
effective_date: { type: string, format: date }
amendment_data: { type: object, additionalProperties: true }
created_at: { type: string, format: date-time }
ContractAmendmentList:
type: object
properties:
data:
type: object
properties:
contract_amendments:
type: array
items: { $ref: '#/components/schemas/ContractAmendment' }
ContractAmendmentEnvelope:
type: object
properties:
data:
type: object
properties:
contract_amendment: { $ref: '#/components/schemas/ContractAmendment' }
ContractAmendmentCreateRequest:
type: object
required: [employment_id, effective_date]
properties:
employment_id: { type: string, format: uuid }
effective_date: { type: string, format: date }
amendment_data: { type: object, additionalProperties: true }
ContractDocument:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
status:
type: string
enum: [draft, pending_signature, signed, voided]
document_url: { type: string, format: uri }
created_at: { type: string, format: date-time }
ContractDocumentEnvelope:
type: object
properties:
data:
type: object
properties:
contract_document: { $ref: '#/components/schemas/ContractDocument' }
Offboarding:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
status:
type: string
enum: [submitted, review_started, submitted_to_payroll, completed, deleted]
offboarding_type:
type: string
enum: [resignation, termination, end_of_contract]
last_day_of_work: { type: string, format: date }
reason_for_offboarding: { type: string }
OffboardingEnvelope:
type: object
properties:
data:
type: object
properties:
offboarding: { $ref: '#/components/schemas/Offboarding' }
OffboardingCreateRequest:
type: object
required: [employment_id, offboarding_type, last_day_of_work]
properties:
employment_id: { type: string, format: uuid }
offboarding_type:
type: string
enum: [resignation, termination, end_of_contract]
last_day_of_work: { type: string, format: date }
reason_for_offboarding: { type: string }
additional_information: { type: object, additionalProperties: true }
TravelLetterRequest:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
destination_country: { type: string }
purpose: { type: string }
status:
type: string
enum: [requested, approved_by_manager, approved_by_remote, declined_by_manager, declined_by_remote]
travel_start_date: { type: string, format: date }
travel_end_date: { type: string, format: date }
TravelLetterRequestList:
type: object
properties:
data:
type: object
properties:
travel_letter_requests:
type: array
items: { $ref: '#/components/schemas/TravelLetterRequest' }
TravelLetterRequestEnvelope:
type: object
properties:
data:
type: object
properties:
travel_letter_request: { $ref: '#/components/schemas/TravelLetterRequest' }
WorkAuthorizationRequest:
type: object
properties:
id: { type: string, format: uuid }
employment_id: { type: string, format: uuid }
country_code: { type: string }
status:
type: string
enum: [requested, approved_by_manager, approved_by_remote, declined_by_manager, declined_by_remote, cancelled]
visa_type: { type: string }
target_start_date: { type: string, format: date }
WorkAuthorizationRequestList:
type: object
properties:
data:
type: object
properties:
work_authorization_requests:
type: array
items: { $ref: '#/components/schemas/WorkAuthorizationRequest' }
WorkAuthorizationRequestEnvelope:
type: object
properties:
data:
type: object
properties:
work_authorization_request: { $ref: '#/components/schemas/WorkAuthorizationRequest' }