Document uploads
Documents are uploaded separately and then attached to accounts or persons as part of the verification process.
They are used to satisfy requirements related to identity and business verification.
Upload a file
Upload a document using the Files API.
POST /v1/files
The request must be sent as multipart/form-data.
Required fields
- file — the binary file content
- purpose — the intended usage of the file (for example:
identity_document)
Example response
Response
{
"id": "file_123",
"purpose": "identity_document"
}
Attach a document
After uploading a file, attach it to an account or person to satisfy verification requirements.
Attach to a person
POST /v1/accounts/{account_id}/persons/{person_id}
{
"verification": {
"document": {
"front": "file_123"
}
}
}
Attach to an account
POST /v1/accounts/{account_id}
{
"company": {
"verification": {
"document": {
"front": "file_123"
}
}
}
}
Relationship to requirements
Document uploads are driven by the account requirements.
Missing documents appear in:
requirements.currently_duerequirements.past_due
Example:
{
"requirements": {
"currently_due": [
"company.verification.document"
]
}
}
Your platform should:
- Detect required documents from the requirements field
- Prompt the user to upload them
- Attach the uploaded files to the appropriate resource
Behavior
- Files are immutable after upload
- Files can be reused across multiple updates
- Files are referenced by their identifier (for example:
file_123)
Validation and retries
If a document is invalid or rejected:
- The requirement will reappear in the account
- The document must be re-uploaded and re-attached
Always rely on the requirements field to determine whether a document has been accepted or needs to be resubmitted.
Notes
- Documents are scoped to your platform account
- A file must be uploaded before it can be attached
- Attaching a file does not guarantee verification; it initiates the verification process
