Skip to main content
A file is bytes Lead holds plus a small amount of declared metadata, including type. A file is uploaded so that it can be linked to another object, such as an Entity, Application, or User Account. An example would be uploading a signed loan agreement, for it to be linked to an Application or User Account. You can create files, but you can never modify, delete, or download them. A file always carries a type (e.g. passport or loan agreement) that must be declared at file creation.
The Files API is currently in preview with a planned beta release in December 2026. Preview APIs are not yet available in sandbox or production and can change before beta. Use these pages to plan an integration, not to build one. Once released in beta, it will be available to all partners in sandbox, and in production for select programs. Beta APIs may change without a version increment, and changes will be announced in advance. See Versioning and backwards compatibility.

​
How files relate to the rest of the model

Files are linked to three objects:
  • Entity: Create an Entity and link files to the identity documents or additional documents arrays.
  • Applications: Create an application and link files to the documents array.
  • User Accounts: Create a user account and link files to the documents array.

​
Where it fits in onboarding

A file can be created before or after the objects they’re intended to be linked to. Lead recommends the following sequence:
1

Upload each file

Call POST /v2/files once per file, in parallel. Each returns a file_id. You can upload multiple files in parallel.
2

Create the object with file IDs

Call POST /v2/entities, /v2/applications, or /v2/user_accounts with file_ids in the document arrays.
If you need to link files after the object is created:
1

Create the object without documents

Create your Entity, Application, or User Account object with no documents (documents: [] on Applications and User Accounts; identification_documents: [] and additional_documents: [] or no file_ids on Entity identification_document or additional_document entries).
2

Upload each file

Call POST /v2/files once per file, in parallel. Each returns a file_id.
3

Link the files

Call PATCH /v2/entities/{id}, /v2/applications/{id}, or /v2/user_accounts/{id} with file_ids in the document arrays.
A file can be linked to any number of objects (e.g., a single privacy policy for your product may be uploaded once and linked to multiple User Accounts), but the same file can only be linked to the same object once (e.g., you cannot link a single privacy policy to a single User Account multiple times).
Lead recommends uploading a single file that aligns with a single type (e.g. one PDF containing just terms of use). If your file contains more than one type (e.g. one PDF containing both terms of use and a privacy policy), upload the file twice with unique types, and link each unique file to the intended object.
Objects have specific file types that are allowed to be linked. For example, a passport can be linked to an Entity object, but it cannot be linked to an Application object.
If you accidentally link the wrong file, or create the file with an impermissible type for the intended object, you’ll need to create a new file, and PATCH the document array with the new file_id.

​
What you can do

  • POST /v2/files: Create a file.
  • GET /v2/files/{id}: Retrieve a file and its metadata.
  • Link a file to any number of objects.

​
Authentication

  • file/read_write to create a file. Also grants read access.
  • file/read for the GET endpoint only. Use this to retrieve a file’s metadata.

​
What you cannot do

  • Change a file. Once created, the file cannot be changed.
  • Delete a file. Once created, the file cannot be deleted.
  • Download a file’s contents.
  • Link the same file to the same object more than once.
  • Link a file to an object’s document array that does not permit that file type.
  • Subscribe to webhooks. Files cannot be changed after creation, so Lead emits no events for them.

​
In this section