Remote Files API
The Files API from Remote — 3 operation(s) for files.
OpenAPI Specification
openapi: 3.0.0
info:
title: Remote Address Details Files API
version: 0.1.0
servers:
- url: https://gateway.remote.com/
variables: {}
- url: https://gateway.remote-sandbox.com/
variables: {}
security:
- OAuth2: []
tags:
- name: Files
paths:
/v1/files/{id}:
get:
callbacks: {}
deprecated: false
description: 'Downloads a file.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |
'
operationId: get_v1_files_id
parameters:
- description: File ID
example: 93t3j-file-id-9suej43
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadFileResponse'
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
- document:read
- document:write
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- document:read
- document:write
- employment_documents
- all:write
- all:read
summary: Download file
tags:
- Files
/v1/employments/{employment_id}/files:
get:
callbacks: {}
deprecated: false
description: 'Lists files associated with a specific employment.
Supports filtering by file type and sub_type.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | View documents (`document:read`) | Manage documents (`document:write`) |
'
operationId: get_v1_employments_employment_id_files
parameters:
- description: Employment ID
example: emp-123456
in: path
name: employment_id
required: true
schema:
type: string
- description: Filter by file type (optional)
example: contract
in: query
name: type
required: false
schema:
type: string
- description: Filter by file sub_type (optional)
example: personal_id
in: query
name: sub_type
required: false
schema:
type: string
- description: Starts fetching records after the given page
example: 1
in: query
name: page
required: false
schema:
default: 1
minimum: 1
type: integer
- description: Number of items per page
example: 20
in: query
name: page_size
required: false
schema:
default: 20
maximum: 100
minimum: 1
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListFilesResponse'
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
- document:read
- document:write
- employment_documents
- all:write
- all:read
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- document:read
- document:write
- employment_documents
- all:write
- all:read
summary: List employment files
tags:
- Files
/v1/documents:
post:
callbacks: {}
deprecated: false
description: 'Uploads a file associated with a specified employment.
Please contact api-support@remote.com to request access to this endpoint.
## Scopes
| Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|
| Manage employment documents (`employment_documents`) | - | Manage documents (`document:write`) |
'
operationId: post_v1_documents
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
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FileParams'
description: File
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UploadFileResponse'
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
- document:write
- employment_documents
- all:write
OAuth2AuthorizationCode:
- https://gateway.remote.com/company.manage
- document:write
- employment_documents
- all:write
summary: Upload file
tags:
- Files
components:
schemas:
UploadFileResponse:
additionalProperties: false
description: Response returned after successfully uploading a file.
example:
data:
file:
id: 9880b711-file-id-ecf8f551bd78
inserted_at: '2021-07-15T18:18:17Z'
name: id.pdf
sub_type: personal_id
type: id
properties:
data:
properties:
file:
$ref: '#/components/schemas/File'
required:
- file
type: object
title: UploadFileResponse
type: object
DateTimeIso8601:
description: 'UTC date time in [ISO 8601][] format.
[ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
'
example: '2021-07-15T18:18:17Z'
format: date-time
title: DateTimeIso8601
type: string
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
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
ListFilesResponse:
description: Response schema listing many files
example:
current_page: 1
files:
- id: 9880b711-file-id-ecf8f551bd78
inserted_at: '2021-07-15T18:18:17Z'
name: id.pdf
sub_type: personal_id
type: id
total_count: 1
total_pages: 1
properties:
data:
properties:
current_page:
description: The current page among all of the total_pages
type: integer
files:
items:
$ref: '#/components/schemas/File'
type: array
total_count:
description: The total number of records in the result
type: integer
total_pages:
description: The total number of pages the user can go through
type: integer
type: object
title: ListFilesResponse
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
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
FileParams:
additionalProperties: false
description: Parameters to upload a file
example:
employment_id: 5e55386e-4f4f-4def-92f4-bdc19a5ce77d
file: base64_encoded_file_content
sub_type: ir_35
type: contract
properties:
employment_id:
description: The unique identifier (UUID) of the employment to attach this file to.
type: string
file:
description: The file content, base64-encoded.
format: binary
type: string
sub_type:
description: A more specific classification within the type (e.g., "ir_35" for a UK contractor tax determination).
type: string
type:
description: The broad category of the file (e.g., "contract", "id", "tax_form").
type: string
required:
- file
- employment_id
title: FileParams
type: object
File:
additionalProperties: false
description: A file associated with an employment, such as a contract, tax form, or identity document.
example:
id: 9880b711-file-id-ecf8f551bd78
inserted_at: '2021-07-15T18:18:17Z'
name: id.pdf
sub_type: personal_id
type: id
properties:
id:
description: The unique identifier (UUID) of the file.
type: string
inserted_at:
$ref: '#/components/schemas/DateTimeIso8601'
name:
description: The file name including extension (e.g., "id.pdf", "contract.pdf").
type: string
sub_type:
description: A more specific classification of the file within its type (e.g., "personal_id" within type "id", or "ir_35" within type "contract"). Null if no sub-type applies.
nullable: true
type: string
type:
description: The broad category of the file (e.g., "id", "contract", "tax_form").
type: string
required:
- id
- inserted_at
- name
- type
title: File
type: object
ActionError:
properties:
action:
description: The action that lead to the error message.
type: string
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
required:
- code
- message
- action
title: ActionError
type: object
DownloadFileResponse:
additionalProperties: false
description: Response containing the file's metadata and its base64-encoded content for download.
example:
data:
file:
content: data:application/pdf;base64,iVBORw0KGgoAAAANSUhEUgAAAJUAAACVCAYAAABRorhPAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWF...
id: 9880b711-file-id-ecf8f551bd78
inserted_at: '2021-07-15T18:18:17Z'
name: id.pdf
sub_type: personal_id
type: id
properties:
data:
properties:
file:
properties:
content:
format: binary
type: string
id:
type: string
inserted_at:
$ref: '#/components/schemas/DateTimeIso8601'
name:
type: string
sub_type:
nullable: true
type: string
type:
type: string
required:
- content
- id
- inserted_at
- name
- type
type: object
required:
- file
type: object
required:
- data
title: DownloadFileResponse
type: object
securitySchemes:
BasicAuth:
description: 'Authenticate using the basic authentication for partners.
Use the CLIENT_ID as login and CLIENT_SECRET as password.
'
scheme: basic
type: http
ClientToken:
description: 'Authenticate a partner using only the the provided `client_token`.
This authentication method only allows accessing marketing endpoints.
'
scheme: bearer
type: http
CustomerAPIToken:
description: 'Authenticate using API Key generated by the customer in their Integration Settings page.
'
scheme: bearer
type: http
OAuth2:
description: 'Authenticate using OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2Assertion:
description: 'Authenticate as the employee using the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant in the OAuth2 protocol.
'
flows:
clientCredentials:
scopes:
address:read: address:read
address:write: address:write
bank_account:read: bank_account:read
bank_account:write: bank_account:write
document:read: document:read
document:write: document:write
emergency_contact:read: emergency_contact:read
emergency_contact:write: emergency_contact:write
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
expense:read: expense:read
incentive:read: incentive:read
payroll: payroll
payslip:read: payslip:read
personal_detail:read: personal_detail:read
personal_detail:write: personal_detail:write
time_and_attendance: time_and_attendance
timeoff:read: timeoff:read
timeoff:write: timeoff:write
timesheet:read: timesheet:read
tokenUrl: /auth/oauth2/token
x-assertionType: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
type: oauth2
OAuth2AuthorizationCode:
description: 'Authenticate as the token authorizer using `authorization_code` / `refresh_token` grants in the OAuth 2.0 protocol.
'
flows:
authorizationCode:
authorizationUrl: /auth/oauth2/authorize
refreshUrl: /auth/oauth2/token
scopes:
company_department:read: company_department:read
webhook:write: webhook:write
magic_link:write: magic_link:write
offboarding:write: offboarding:write
custom_field:write: custom_field:write
address:write: address:write
expense:read: expense:read
employment:write: employment:write
identity_verification:write: identity_verification:write
timesheet:write: timesheet:write
travel_letter:write: travel_letter:write
incentive:read: incentive:read
personal_detail:read: personal_detail:read
invoices:write: invoices:write
work_authorization:write: work_authorization:write
timeoff:write: timeoff:write
company_structure:read: company_structure:read
benefit_renewal:write: benefit_renewal:write
benefit_offer:read: benefit_offer:read
employment_documents: employment_documents
onboarding:write: onboarding:write
payroll_run:read: payroll_run:read
risk_reserve:write: risk_reserve:write
invoices: invoices
resignation_letter:read: resignation_letter:read
resignation:read: resignation:read
convert_currency:read: convert_currency:read
employments: employments
probation_document:read: probation_document:read
company_admin: company_admin
payroll: payroll
help_center_article:read: help_center_article:read
timesheet:read: timesheet:read
custom_field_value:write: custom_field_value:write
company_currencies:read: company_currencies:read
payslip:read: payslip:read
pay_item:write: pay_item:write
resignation:write: resignation:write
custom_field:read: custom_field:read
payroll_calendar:read: payroll_calendar:read
contract_amendment:write: contract_amendment:write
offboarding:read: offboarding:read
timeoff:read: timeoff:read
probation_document:write: probation_document:write
country:read: country:read
webhook:read: webhook:read
company_department:write: company_department:write
company_manager:read: company_manager:read
pay_item:read: pay_item:read
contract_amendment:read: contract_amendment:read
company:read: company:read
sso_configuration:write: sso_configuration:write
benefit_offer:write: benefit_offer:write
contract_eligibility:write: contract_eligibility:write
benefit_renewal:read: benefit_renewal:read
background_check:read: background_check:read
custom_field_value:read: custom_field_value:read
expense:write: expense:write
identity_verification:read: identity_verification:read
address:read: address:read
document:write: document:write
time_and_attendance: time_and_attendance
employment_payments: employment_payments
form:read: form:read
work_authorization:read: work_authorization:read
invoices:read: invoices:read
incentive:write: incentive:write
employment:read: employment:read
contract:read: contract:read
company_manager:write: company_manager:write
travel_letter:read: travel_letter:read
document:read: document:read
sso_configuration:read: sso_configuration:read
tokenUrl: /auth/oauth2/token
type: oauth2
OAuth2ClientCredentials:
description: 'Authenticate using `client_credentials` grant in the OAuth 2.0 protocol.
'
flows:
clientCredentials:
scopes:
company:read: company:read
company:write: company:write
company_admin: company_admin
company_management: company_management
convert_currency:read: convert_currency:read
country:read: country:read
employment_documents: employment_documents
employment_payments: employment_payments
employments: employments
help_center_article:read: help_center_article:read
invoices: invoices
payroll: payroll
payroll_calendar:read: payroll_calendar:read
pricing_plan:read: pricing_plan:read
pricing_plan:write: pricing_plan:write
time_and_attendance: time_and_attendance
webhook:read: webhook:read
webhook:write: webhook:write
tokenUrl: /auth/oauth2/token
type: oauth2