Skip to main content
Every investment account must complete Know Your Customer (KYC) verification before trading. Bluum handles the compliance pipeline — you collect documents from the user and submit them through the API.

​
How KYC works

Upload Documents → Processing → Approved / Rejected
                       │
                  (auto-approved
                   in sandbox)
  1. Create an account with identity and contact information
  2. Upload identity documents (government-issued ID, proof of address)
  3. Bluum verifies the documents against the identity information
  4. Account is approved or rejected
In sandbox, documents are auto-approved. In production, verification typically completes within minutes but may take up to 24 hours for manual review.

​
Document types

TypeDescriptionRequired
id_verificationGovernment-issued photo ID (passport, driver’s license, national ID)Yes
proof_of_addressUtility bill, bank statement, or tax document showing current addressSituational
w9_formW-9 tax formSituational

​
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/drivers-license.jpg"
Supported file formats: JPEG, PNG, PDF. Maximum file size: 10MB.

​
Document statuses

StatusMeaning
processingDocument uploaded, verification in progress
approvedVerification successful
rejectedVerification failed — upload a new document

​
Checking document status

Poll the document endpoint or use webhooks: 
# Get a specific document
curl -X GET "$BASE_URL/documents/{document_id}" \
  -H "Authorization: Basic $AUTH"

# List all documents for an account
curl -X GET "$BASE_URL/documents/accounts/$ACCOUNT_ID/upload?status=approved" \
  -H "Authorization: Basic $AUTH"
Use webhooks to receive real-time notifications when document verification completes, rather than polling.

​
Handling rejections

When a document is rejected, the response includes a reason. Common rejection reasons:
ReasonResolution
Document is blurry or illegibleRe-upload with higher quality image
Document is expiredUpload a current, non-expired document
Name mismatchEnsure the name on the document matches the account identity
Document type not acceptedUse a supported government-issued photo ID
Prompt the user to upload a replacement document. There is no limit on upload attempts.

​
Compliance workflow statuses

For more complex compliance scenarios, Bluum uses a multi-step compliance workflow:
StatusMeaning
IN_PROGRESSCompliance checks are running
PENDING_REVIEWRequires manual review
APPROVEDAll checks passed
REJECTEDOne or more checks failed
SUSPENDEDAccount compliance suspended
EXPIREDCompliance window expired, re-verification needed

​
Key endpoints

MethodPathDescription
POST/documents/accounts/{account_id}/uploadUpload a document
GET/documents/{document_id}Get document status
GET/documents/accounts/{account_id}/uploadList account documents