The File Object

A file is a document, an image or a video stored in a workspace and attached to a check. Files
are written and read through two distinct identifiers: an upload_ref on the way in, a file id
on the way out.

Uploading

POST /v1/files/upload accepts one file as multipart/form-data, in a form field named file,
and returns a reference.

curl -X POST https://api.dotfile.com/v1/files/upload \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -F "file=@registration_certificate.pdf"

{
  "upload_ref": "dG1wL3Rlc3QtMTY3NDE0MjAzMjMxNy5wZGYsYXBwbGljYXRpb24vcGRmLHRlc3QucGRm",
  "expired_at": "2026-08-12T09:41:07.000Z"
}

Constraint	Value
Maximum size	20 MB. Providers apply lower limits: see ID Document
Validity	approximately one day, returned as `expired_at`
Accepted formats	image, office, text and archive formats. The complete list, with extensions and MIME types, is generated from the code on Upload a file

Response	Condition
`400`	the file is missing or empty
`413`	the file exceeds 20 MB
`415`	the format is not accepted

An uploaded file is not attached to anything until a check references it.

Attaching to a check

Two check types accept an upload_ref, at creation or on an existing check.

Check type	Field	Constraint
`document`	`data.files[].upload_ref`	maximum 10 files
`id_document`	`data.front_upload_ref`, `data.back_upload_ref`	`back_upload_ref` is optional and `null` for a passport

curl -X POST https://api.dotfile.com/v1/checks/document \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "a7402197-0314-4c8f-8146-15ec0fa02193",
    "settings": {"document_type_key": "financial_statements"},
    "data": {"files": [{"upload_ref": "'$UPLOAD_REF'"}]}
  }'

A reference that has expired, or that no longer resolves to a stored file, is rejected with 400
and the check is not created. Add files and
Add files accept the same fields on an existing check.

Downloading

GET /v1/files/{id} returns the file content as binary/octet-stream. There is no metadata
endpoint: the file name and MIME type are not returned by this call.

curl https://api.dotfile.com/v1/files/$FILE_ID \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -o registration_certificate.pdf

File identifiers are returned on the object that carries the file:

Source	Field
`document` check	`data.document_file_ids`
`id_document` check	`data.information.front_file_id`, `back_file_id`
`id_verification` check	`data.information.front_file_id`, `back_file_id`, `face_file_id`, `video_file_id`, `signature_file_id`, and `data.vendor.report_file_id`
`electronic_signature` check	`data.information.file_id`, `signed_file_id`
Case documents	`file_ids`, from Retrieve case's documents
Document order	`file_id`, once the order is completed

In a browser, request the file as a blob so that the API key stays in a header rather than in a
navigated URL:

import { saveAs } from 'file-saver';
import axios from 'axios';

const res = await axios.get(`https://api.dotfile.com/v1/files/${fileId}`, {
  responseType: 'blob',
  headers: { 'X-DOTFILE-API-KEY': process.env.DOTFILE_API_KEY },
});

saveAs(res.data, 'report.pdf');

There is no endpoint to list or to delete files. A file is reachable only through the object
that carries its identifier.

Uploading

Attaching to a check

Downloading

Endpoints