Phase 3: Organization Verification Organization verification (KYB - Know Your Business) is more comprehensive than individual verification, including business entity verification, UBO verification, and financial statement review.
Verification Requirements Verification Type Description BUSINESS_VERIFICATIONCompany registration and legal status DOCUMENT_VERIFICATIONBusiness documents authentication BENEFICIAL_OWNER_VERIFICATIONUBO identification and verification FINANCIAL_VERIFICATIONFinancial statements review
Required Documents Document Type Description Format Max Size CERTIFICATE_OF_INCORPORATIONOfficial incorporation certificate PDF 5 MB ARTICLES_OF_ASSOCIATIONCompany articles PDF 10 MB PROOF_OF_REGISTERED_ADDRESSUtility bill or bank statement PDF/JPEG 5 MB BENEFICIAL_OWNERS_DECLARATIONUBO declaration form PDF 5 MB FINANCIAL_STATEMENTSLatest audited statements PDF 20 MB DIRECTOR_IDSID documents for each director PDF/JPEG 5 MB each BANK_REFERENCE_LETTERBank reference letter PDF 5 MB BUSINESS_LICENSEIndustry-specific licenses PDF 5 MB TAX_CLEARANCE_CERTIFICATETax authority clearance PDF 5 MB
Initiate Organization Verification Endpoint: POST /api/v2.1/customer/organization/{organizationId}/verifyRequired Role: COMPLIANCE_OFFICER or ADMIN_USERHeaders: X-User-ID : user-660e8400-e29b-41d4-a716-446655440011 X-User-Roles : COMPLIANCE_OFFICER Authorization : Bearer {jwt-token}
Request Body: { "verificationType" : "KYB" , "verificationLevel" : "ENHANCED" , "priority" : "NORMAL" , "verificationData" : { "businessType" : "B2B" , "annualRevenue" : "5000000" , "employeeCount" : "50" , "businessDescription" : "Enterprise software development" , "mainProducts" : [ "Software Development" , "Cloud Services" ], "targetMarkets" : [ "UK" , "EU" , "US" ], "regulatoryCompliance" : [ "GDPR" , "PCI-DSS" , "ISO27001" ], "bankingRelationships" : [ { "bankName" : "Westminster Bank" , "accountNumber" : "12345678" , "sortCode" : "12-34-56" } ] } }
Status: 200 OK{ "code" : 200 , "message" : "Verification initiated successfully" , "data" : { "verificationId" : "verif-ff0e8400-e29b-41d4-a716-446655440160" , "organizationId" : "org-880e8400-e29b-41d4-a716-446655440110" , "status" : "IN_PROGRESS" , "type" : "IDENTITY_VERIFICATION" , "level" : "ENHANCED" , "startedAt" : "2026-01-13T12:00:00.000Z" , "dueDate" : "2026-01-20T12:00:00.000Z" , "requiredDocuments" : [ "CERTIFICATE_OF_INCORPORATION" , "ARTICLES_OF_ASSOCIATION" , "PROOF_OF_REGISTERED_ADDRESS" , "BENEFICIAL_OWNERS_DECLARATION" , "FINANCIAL_STATEMENTS" , "BANK_REFERENCE_LETTER" , "DIRECTOR_IDS" , "BUSINESS_LICENSE" , "TAX_CLEARANCE_CERTIFICATE" ], "verificationTypes" : [ "BUSINESS_VERIFICATION" , "DOCUMENT_VERIFICATION" , "BENEFICIAL_OWNER_VERIFICATION" , "FINANCIAL_VERIFICATION" ], "assignedTo" : "compliance-team" , "estimatedCompletionTime" : "3-5 business days" } }
Status: 403 Forbidden{ "code" : 403 , "message" : "Access denied: Only COMPLIANCE_OFFICER or ADMIN_USER can initiate verification" , "data" : { "userId" : "user-660e8400..." , "currentRoles" : [ "EMPLOYEE" , "TRANSACTION_APPROVER" ], "requiredRoles" : [ "COMPLIANCE_OFFICER" , "ADMIN_USER" ] } }
Upload Verification Document Use the generic verification document endpoint for both individual and organization verifications.
Endpoint: POST /api/v2.1/verifications/{verificationId}/documentsContent-Type: application/jsonHeaders: Authorization : Bearer {jwt-token} Content-Type : application/json
Request Body: { "docId" : "550e8400-e29b-41d4-a716-446655440000" , "documentType" : "CERTIFICATE_OF_INCORPORATION" , "fileName" : "certificate_of_incorporation.pdf" , "fileContent" : "JVBERi0xLjQKJeLjz9MKMyAwIG9iaiA8PAovVHlwZSAvUGFnZQovUGFy..." , "customerId" : "org-880e8400-e29b-41d4-a716-446655440110" , "description" : "Certificate of Incorporation - Acme Corp" , "documentCategory" : "VERIFICATION" , "metadata" : { "issuer" : "Companies House" , "issueDate" : "2010-05-20" , "documentNumber" : "REG123456789" , "certificateType" : "ORIGINAL" } }
Field Descriptions:
fileContent: Base64-encoded file contentdocumentCategory: Use VERIFICATION for KYB documentscustomerId: Organization ID (from verification initiation) Status: 201 Created{ "code" : 201 , "message" : "Document uploaded successfully" , "data" : { "documentId" : "doc-0011e8400-e29b-41d4-a716-446655440170" , "verificationId" : "verif-ff0e8400-e29b-41d4-a716-446655440160" , "customerId" : "org-880e8400-e29b-41d4-a716-446655440110" , "documentType" : "CERTIFICATE_OF_INCORPORATION" , "fileName" : "certificate_of_incorporation.pdf" , "fileSize" : 2048576 , "uploadedAt" : "2026-01-13T13:00:00.000Z" , "status" : "UPLOADED" , "verificationStatus" : "IN_PROGRESS" } }
Get Verification Status Endpoint: GET /api/v2.1/customer/organization/{organizationId}/verification
Status: 200 OK{ "code" : 200 , "message" : "Verification status retrieved successfully" , "data" : { "organizationId" : "org-880e8400-e29b-41d4-a716-446655440110" , "verificationId" : "verif-ff0e8400-e29b-41d4-a716-446655440160" , "status" : "PENDING_REVIEW" , "type" : "IDENTITY_VERIFICATION" , "level" : "TENANT_VERIFIED" , "startedAt" : "2026-01-13T12:00:00.000Z" , "completedAt" : null , "expiresAt" : "2026-04-13T12:00:00.000Z" , "submittedDocuments" : 5 , "documentStatus" : { "CERTIFICATE_OF_INCORPORATION" : "SUBMITTED" , "ARTICLES_OF_ASSOCIATION" : "SUBMITTED" , "PROOF_OF_REGISTERED_ADDRESS" : "SUBMITTED" , "BENEFICIAL_OWNERS_DECLARATION" : "SUBMITTED" , "FINANCIAL_STATEMENTS" : "SUBMITTED" , "DIRECTOR_IDS" : "PENDING" , "BANK_REFERENCE_LETTER" : "PENDING" }, "verificationHistory" : [ { "status" : "IN_PROGRESS" , "timestamp" : "2026-01-13T12:00:00.000Z" , "actor" : "COMPLIANCE_OFFICER" }, { "status" : "PENDING_REVIEW" , "timestamp" : "2026-01-14T10:00:00.000Z" , "actor" : "system" , "note" : "All required documents submitted" } ], "nextSteps" : [ "Upload remaining director ID documents" , "Upload bank reference letter" , "Wait for tenant admin review" ] } }
Verification Status Flow Approve Verification (Admin) Endpoint: POST /api/v2.1/verifications/{verificationId}/approveHeaders: Authorization : Bearer {admin-jwt-token} X-User-ID : admin-user-id X-User-Roles : COMPLIANCE_OFFICER
Request Body: { "adminNotes" : "All documents verified. Organization identity confirmed." , "approvedBy" : "ADMIN_USER" , "approvalReason" : "All documents verified for organization customer" }
Status: 200 OK{ "code" : 200 , "message" : "Verification approved successfully" , "data" : { "level" : "TENANT_VERIFIED" , "approvedBy" : "admin-user" , "approvedAt" : "2026-01-15T10:00:00.000Z" , "verificationId" : "verif-ff0e8400-e29b-41d4-a716-446655440160" , "status" : "APPROVED" } }
Next Step After verification is APPROVED, proceed to Phase 4: Consent Management .
Phase 4: Consent Management Accept organization-level consents
