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:- Create the file. Call Create file with the
categoryand thecontentTypeof the file. The file starts with thependingstatus, and the response includes anuploadobject with aurl, theformDatato send and anexpiresAttime. - Upload the content. Send a multipart
POSTrequest with the content directly toupload.url, beforeupload.expiresAt. Include every field offormData, and aContent-Typethat matches thecontentTypeof the file. See the examples in Create file. - Wait until it’s uploaded. The file moves to the
uploadedstatus once the content is processed, which happens asynchronously. No webhook is sent, so poll Get file until thestatusisuploaded. - Use the file. Reference the file
idin the endpoint that needs it, such as the KYC processes that verify the identity or the address of a user. Each endpoint says whichcategoryof file it expects.
pending, or of another category, fails with a 409 file_invalid error.
Categories and limits
Every file has acategory, 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 adownload 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. Sendmetadata 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.