openapi: 3.1.0
info:
title: Remote Files And Custom Fields API
description: |
Upload, download, and reference files attached to companies and
employments on Remote. Also covers custom-field definitions and values,
plus the supported-countries catalog used to look up jurisdiction-aware
JSON Schema forms across the rest of the platform.
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: Files
description: Document upload and retrieval
- name: Custom Fields
description: Customer-defined fields on companies and employments
- name: Countries
description: List of countries Remote supports
- name: Cost Calculator
description: Estimate the loaded cost of hiring in a given country
paths:
/files:
post:
summary: Upload A File
operationId: uploadFile
tags: [Files]
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required: [file, attachable_id, attachable_type]
properties:
file:
type: string
format: binary
attachable_id:
type: string
format: uuid
attachable_type:
type: string
enum: [employment, company, expense, contract_document]
category:
type: string
description: Optional file category tag.
responses:
'201':
description: Uploaded.
content:
application/json:
schema: { $ref: '#/components/schemas/FileEnvelope' }
/files/{file_id}:
parameters:
- { name: file_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: Download A File
operationId: downloadFile
tags: [Files]
responses:
'200':
description: File binary or signed URL.
content:
application/octet-stream:
schema: { type: string, format: binary }
application/json:
schema:
type: object
properties:
data:
type: object
properties:
download_url: { type: string, format: uri }
expires_at: { type: string, format: date-time }
/custom_fields:
get:
summary: List Custom Field Definitions
operationId: listCustomFieldDefinitions
tags: [Custom Fields]
parameters:
- { name: scope, in: query, schema: { type: string, enum: [company, employment] } }
responses:
'200':
description: Custom field definitions.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
custom_fields:
type: array
items: { $ref: '#/components/schemas/CustomFieldDefinition' }
post:
summary: Create A Custom Field Definition
operationId: createCustomFieldDefinition
tags: [Custom Fields]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CustomFieldDefinition' }
responses:
'201':
description: Created.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
custom_field: { $ref: '#/components/schemas/CustomFieldDefinition' }
/custom_fields/{custom_field_id}/values:
parameters:
- { name: custom_field_id, in: path, required: true, schema: { type: string, format: uuid } }
get:
summary: List Custom Field Values
operationId: listCustomFieldValues
tags: [Custom Fields]
parameters:
- { name: subject_id, in: query, schema: { type: string, format: uuid } }
responses:
'200':
description: Values.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
values:
type: array
items: { $ref: '#/components/schemas/CustomFieldValue' }
put:
summary: Upsert A Custom Field Value
operationId: upsertCustomFieldValue
tags: [Custom Fields]
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CustomFieldValue' }
responses:
'200':
description: Upserted.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
value: { $ref: '#/components/schemas/CustomFieldValue' }
/countries:
get:
summary: List Supported Countries
operationId: listCountries
tags: [Countries]
responses:
'200':
description: Countries.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
countries:
type: array
items: { $ref: '#/components/schemas/Country' }
/countries/{country_code}:
parameters:
- { name: country_code, in: path, required: true, schema: { type: string, description: ISO 3166-1 alpha-3 country code. } }
get:
summary: Show A Country
operationId: showCountry
tags: [Countries]
responses:
'200':
description: Country.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
country: { $ref: '#/components/schemas/Country' }
/cost_calculator/estimate:
post:
summary: Estimate Employment Cost
description: |
Returns the loaded cost of hiring an employee under EOR or Global
Payroll, including statutory contributions and Remote platform fees.
operationId: estimateEmploymentCost
tags: [Cost Calculator]
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [country_code, employment_model, annual_gross_salary, currency]
properties:
country_code: { type: string }
employment_model:
type: string
enum: [global_payroll, peo, eor]
annual_gross_salary: { type: integer }
currency: { type: string }
include_benefits: { type: boolean, default: true }
responses:
'200':
description: Cost estimate.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
total_annual_cost: { type: integer }
employer_contributions: { type: integer }
remote_fee: { type: integer }
currency: { type: string }
breakdown:
type: array
items:
type: object
properties:
label: { type: string }
amount: { type: integer }
recurrence:
type: string
enum: [monthly, annual, one_time]
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
File:
type: object
properties:
id: { type: string, format: uuid }
filename: { type: string }
content_type: { type: string }
size: { type: integer }
attachable_id: { type: string, format: uuid }
attachable_type:
type: string
enum: [employment, company, expense, contract_document]
category: { type: string, nullable: true }
created_at: { type: string, format: date-time }
download_url: { type: string, format: uri }
FileEnvelope:
type: object
properties:
data:
type: object
properties:
file: { $ref: '#/components/schemas/File' }
CustomFieldDefinition:
type: object
required: [name, scope, type]
properties:
id: { type: string, format: uuid }
name: { type: string }
scope:
type: string
enum: [company, employment]
type:
type: string
enum: [string, number, boolean, date, enum, multiselect]
options:
type: array
items: { type: string }
description: For enum/multiselect types.
required: { type: boolean, default: false }
description: { type: string }
CustomFieldValue:
type: object
required: [subject_id, value]
properties:
id: { type: string, format: uuid }
custom_field_id: { type: string, format: uuid }
subject_id: { type: string, format: uuid }
value:
oneOf:
- { type: string }
- { type: number }
- { type: boolean }
- { type: array, items: { type: string } }
Country:
type: object
properties:
code: { type: string, description: ISO 3166-1 alpha-3 country code. }
name: { type: string }
currency: { type: string }
supported_employment_models:
type: array
items:
type: string
enum: [global_payroll, peo, eor, contractor]
has_remote_entity: { type: boolean }