Working with Files

The Files API lets you list, upload, and download the files on an employee's profile that your API token has access to. Files include documents employers upload, such as company policies or IDs, and documents Remote creates, such as signed contracts and tax forms.

List Files

The List employment files endpoint returns the files on an employment. You can filter by type and sub_type. Each file includes its id, name, type, sub_type, and inserted_at. The list doesn't include file content. Use the file id with Download file to get it.

File types

These are the most common types. Other types and sub types exist.

typeWhat it contains
contractSigned contracts. For contractors, this includes contractor services agreements (CSAs), statements of work (SOWs), and custom contractor agreements. A contractor's contract only appears here once everyone has signed it.
documentOther documents. Files with sub_type: employer_managed_document are documents the company created in Remote from one of its templates and had signed.
tax_documentTax forms, such as W-9s (sub_type: w_9_form).
idIdentity documents, such as sub_type: personal_id.

Files and Contract Documents

For contractors, some documents exist both as a file and as a contract document, listed with List contract documents:

  • Contractor agreements, such as CSAs. Once signed, the PDF is stored as a file with type: contract.
  • Documents the company creates in Remote, shown as "Generic Document" in the dashboard. Once finished, the PDF is stored as a file with type: document and sub_type: employer_managed_document.

The file and the contract document have different IDs, and the API doesn't link them.

⚠️ If you sync both files and contract documents, you can store the same document twice. Pick one source for each document. For contractor agreements, use contract documents, which include status and signatories, and skip type: contract files for contractors. For documents the company creates, use either list, but not both.

Upload File

The Upload file endpoint uploads a document to an employee's profile. The request needs the employment_id and the file. type and sub_type are optional labels for the file. On success, the API returns a unique file ID which can later be used to download the file.

{
  "data": {
    "file": {
      "id": "9880b711-file-id-ecf8f551bd78",
      "inserted_at": "2025-01-02T17:19:21",
      "name": "id.pdf",
      "sub_type": "personal_id",
      "type": "id"
    }
  }
}

ℹ️ The maximum size limit of a file that can be uploaded is 20 MB. You can upload PNG, JPG, JPEG, PDF, DOC, DOCX, XLS, XLSX, RTF, ASICE, SCE, ASICS and SCS files as long as they don't exceed the size limit. Contact [email protected] to request access to this endpoint.

Download File

The Download file endpoint downloads a file using its unique file ID. You can get the ID from the list files response or from a successful upload.

The file is returned in content as a base64 data URI. Its MIME type comes from the extension in the file's name. For example, id.pdf returns data:application/pdf;base64,... and id.png returns data:image/png;base64,....

{
  "data": {
    "file": {
      "content": "data:application/pdf;base64,JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFIvRmlsdGVyIC9GbGF0ZURlY29kZT4+...",
      "id": "9880b711-file-id-ecf8f551bd78",
      "inserted_at": "2025-01-02T17:19:21",
      "name": "id.pdf",
      "sub_type": "personal_id",
      "type": "id"
    }
  }
}

File formats

Files Remote creates, such as signed contracts and tax forms completed in Remote, are PDFs. Uploaded files can be any of the supported formats. To know a file's format without downloading it, check the extension in name from the list files response.


Did this page help you?