> ## Documentation Index
> Fetch the complete documentation index at: https://developer.uphold.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files API introduction

> Upload documents, images and videos to the Uphold platform, such as identity documents and proofs of address, and reference them in KYC and KYB processes.

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](https://developer.uphold.com/rest-apis/core-api/files/create-file.md) 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](https://developer.uphold.com/rest-apis/core-api/files/create-file.md).
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](https://developer.uphold.com/rest-apis/core-api/files/get-file.md) until the `status` is `uploaded`.
4. **Use the file.** Reference the file `id` in the endpoint that needs it, such as the [KYC](https://developer.uphold.com/rest-apis/core-api/kyc/introduction.md#file-based-processes) 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](https://developer.uphold.com/rest-apis/core-api/files/list-files-settings.md) 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](https://developer.uphold.com/rest-apis/core-api/files/get-file.md) 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](https://developer.uphold.com/rest-apis/entity-metadata.md), 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](https://developer.uphold.com/rest-apis/core-api/files/create-file.md), or manage it later with the [metadata endpoints](https://developer.uphold.com/rest-apis/core-api/metadata/set-metadata.md), using `files` as the entity.

| Operation | Scope |
| - | - |
| [Get metadata](https://developer.uphold.com/rest-apis/core-api/metadata/get-metadata.md) | `core.files.metadata:read` |
| [Set metadata](https://developer.uphold.com/rest-apis/core-api/metadata/set-metadata.md), [Update metadata](https://developer.uphold.com/rest-apis/core-api/metadata/update-metadata.md), [Delete metadata](https://developer.uphold.com/rest-apis/core-api/metadata/delete-metadata.md) | `core.files.metadata:write` |
| [Create file](https://developer.uphold.com/rest-apis/core-api/files/create-file.md) with `metadata` | `core.files.metadata:write`, in addition to `core.files:create` |

Without the write scope, a create request that includes `metadata` is rejected with `token_insufficient_scopes`, and the file is not created.
