Upload Document
https://sandboxapi.onbrails.com/api/v2/document-upload (opens in a new tab)
Upload a file and receive a key that references it. Use the key as:
destination.sender.complianceDocument.proofOfIdentitywhen adding a beneficiary (sender identity or business registration document), orreceiptRefwhen initiating a payout (invoice, contract or receipt).
See the Documents & Compliance guide for which document is required when.
Body Parameters
This endpoint accepts multipart/form-data with a single file part.
| Parameter | Type | Required | Description |
|---|---|---|---|
| file | file | ✅ | The document. Accepted types: pdf, png, jpeg/jpg, doc, docx. Maximum size 10 MB. |
Send the request with Content-Type: multipart/form-data, not
application/json. Documents forwarded to payout partners must be pdf,
jpg, jpeg or png and no larger than 5 MB; stay within those limits
for compliance documents and invoices.
Request
curl --request POST \
--url https://sandboxapi.onbrails.com/api/v2/document-upload \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--form 'file=@"/Users/files/Downloads/passport.pdf"'Responses
{
"status": true,
"message": "File uploaded successfully",
"data": {
"key": "documents/45422f21-9a0e-479e-9e10-615556448a78/7b1c6e2a-3f0d-4c8e-9a51-2d6f8e4b9c10.pdf",
"url": "https://brails-documents.s3.amazonaws.com/documents/45422f21-9a0e-479e-9e10-615556448a78/7b1c6e2a-3f0d-4c8e-9a51-2d6f8e4b9c10.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=10800&X-Amz-Signature=...",
"expiresAt": "2026-09-22T15:04:05Z"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
| key | string | Durable reference to the uploaded file. Store this value. It is what you pass as complianceDocument.proofOfIdentity or receiptRef. |
| url | string | Signed link for checking what was uploaded. It stops working at expiresAt (3 hours). Do not persist it. |
| expiresAt | string | ISO 8601 time at which url expires. |
Keys are scoped to your business. A key passed in a beneficiary or payout
request is verified to exist and to belong to you; an unknown or foreign key is
rejected with Upload does not belong to this company (403) or a 400
naming the missing object.
Errors
| Status | Message | Cause / what to do |
|---|---|---|
| 400 | file is required | No file part in the multipart body. |
| 400 | this endpoint does not accept <type> files | Unsupported content type. Send pdf, png, jpeg, doc or docx. |
| 401 | Unauthorized | Missing or invalid secret key. |
| 413 | file exceeds the maximum allowed size | File larger than 10 MB. Compress or split the document and retry. |
| 503 | Storage is not available | Temporary storage outage. Retry later. |