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" \
  -H "Authorization: Basic $AUTH" \
  -F "account_id=$INVESTOR_ID" \
  -F "purpose=kyc" \
  -F "document_type=id_verification" \
  -F "file=@/path/to/drivers-license.jpg"
account_id sets the document’s owner to that investor; omit it to attach the document to the tenant directly. Use user_id to attach to a dashboard user instead. 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?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/documentsUpload a document (multipart)
GET/documentsList documents (filter by account_id, user_id, purpose, status)
GET/documents/{document_id}Get document detail
GET/documents/{document_id}/downloadDownload the document bytes
DELETE/documents/{document_id}Delete a document