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.
type | What it contains |
|---|---|
contract | Signed 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. |
document | Other documents. Files with sub_type: employer_managed_document are documents the company created in Remote from one of its templates and had signed. |
tax_document | Tax forms, such as W-9s (sub_type: w_9_form). |
id | Identity 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: documentandsub_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: contractfiles 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.
Updated 4 days ago