Skip to main content
After creating an account, the user must complete KYC verification by uploading identity documents. This guide covers the upload flow, status tracking, and handling rejections.

​
Upload flow

​
1. Upload a document

curl -X POST "$BASE_URL/documents/accounts/$ACCOUNT_ID/upload" \
  -H "Authorization: Basic $AUTH" \
  -F "document_type=id_verification" \
  -F "file=@/path/to/id-document.jpg"
Accepted formats: JPEG, PNG, PDF (max 10MB) Document types:
  • id_verification — Government-issued photo ID (required)
  • proof_of_address — Utility bill, bank statement (if requested)
  • tax_document — W-9 or equivalent (if requested)

​
2. Track verification status

Option A: Poll 
curl -X GET "$BASE_URL/documents/$DOCUMENT_ID" \
  -H "Authorization: Basic $AUTH"
Option B: Webhooks (recommended) Subscribe to document.approved and document.rejected events: 
curl -X POST "$BASE_URL/webhooks" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/bluum",
    "events": ["document.approved", "document.rejected"]
  }'

​
3. Handle the result

StatusWhat to do
approvedProceed to bank linking and funding
rejectedShow the rejection reason and prompt re-upload

​
Handling rejections

When a document is rejected, the response includes a reason: 
{
  "document_id": "doc_a1b2c3d4e5f6g7h8",
  "upload_status": "rejected",
  "rejection_reason": "Document is expired"
}
Display the reason to your user and allow them to upload a replacement. There is no limit on upload attempts. Common rejection reasons:
  • Document is blurry or illegible
  • Document is expired
  • Name doesn’t match account identity
  • Document type not recognized

​
Listing documents

# All documents for an account
curl -X GET "$BASE_URL/documents/accounts/$ACCOUNT_ID/upload" \
  -H "Authorization: Basic $AUTH"

# Filter by status
curl -X GET "$BASE_URL/documents/accounts/$ACCOUNT_ID/upload?status=approved" \
  -H "Authorization: Basic $AUTH"

​
Sandbox behavior

In sandbox, all document uploads are auto-approved within seconds. To test rejection flows, use specific test values documented in your dashboard.

​
Next steps

Once KYC is approved: