Skip to main content
The files group of endpoints allows users to upload documents, images and videos to the platform, such as an identity document or a proof of address. A file isn’t useful on its own: once uploaded, it’s referenced by its id in other endpoints, such as the KYC processes that verify the user’s identity.

File lifecycle

A file goes through these steps before it can be used:
  1. Create the file. Call Create file with the category and the contentType of the file. The file starts with the pending status, and the response includes an upload object with a url, the formData to send and an expiresAt time.
  2. Upload the content. Send a multipart POST request with the content directly to upload.url, before upload.expiresAt. Include every field of formData, and a Content-Type that matches the contentType of the file. See the examples in Create file.
  3. Wait until it’s uploaded. The file moves to the uploaded status once the content is processed, which happens asynchronously. No webhook is sent, so poll Get file until the status is uploaded.
  4. Use the file. Reference the file id in the endpoint that needs it, such as the KYC processes that verify the identity or the address of a user. Each endpoint says which category of file it expects.
Only an uploaded file of the expected category can be used. Referencing a file that is still pending, or of another category, fails with a 409 file_invalid error.

Categories and limits

Every file has a category, which is document, image or video, and decides which content types and sizes it accepts. Use List files settings to find the allowed content types, the minimum and maximum file size, and how long the upload URL is valid for each category. Creating a file with a content type its category doesn’t allow fails with file_content_type_not_allowed, and creating more files than a user is allowed fails with max_files_limit_exceeded.

Downloading a file

Once a file is uploaded, Get file returns a download object with a signed url to download its content. The URL is only valid until download.expiresAt, so get the file again to download it later.

Metadata

Files support metadata, so you can attach your own data to a file, such as the id of the document in your system, and map it to the records of your own system. Send metadata when you create the file, or manage it later with the metadata endpoints, using files as the entity. Without the write scope, a create request that includes metadata is rejected with token_insufficient_scopes, and the file is not created.