Phase 3: Organization Verification

KYB verification, document upload, and approval workflow

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_VERIFICATION`	Company registration and legal status
`DOCUMENT_VERIFICATION`	Business documents authentication
`BENEFICIAL_OWNER_VERIFICATION`	UBO identification and verification
`FINANCIAL_VERIFICATION`	Financial statements review

Required Documents

Document Type	Description	Format	Max Size
`CERTIFICATE_OF_INCORPORATION`	Official incorporation certificate	PDF	5 MB
`ARTICLES_OF_ASSOCIATION`	Company articles	PDF	10 MB
`PROOF_OF_REGISTERED_ADDRESS`	Utility bill or bank statement	PDF/JPEG	5 MB
`BENEFICIAL_OWNERS_DECLARATION`	UBO declaration form	PDF	5 MB
`FINANCIAL_STATEMENTS`	Latest audited statements	PDF	20 MB
`DIRECTOR_IDS`	ID documents for each director	PDF/JPEG	5 MB each
`BANK_REFERENCE_LETTER`	Bank reference letter	PDF	5 MB
`BUSINESS_LICENSE`	Industry-specific licenses	PDF	5 MB
`TAX_CLEARANCE_CERTIFICATE`	Tax authority clearance	PDF	5 MB

Initiate Organization Verification

Endpoint: POST /api/v2.1/customer/organization/{organizationId}/verify

Required Role: COMPLIANCE_OFFICER or ADMIN_USER

Headers:

http

X-User-ID: user-660e8400-e29b-41d4-a716-446655440011
X-User-Roles: COMPLIANCE_OFFICER
Authorization: Bearer {jwt-token}

Request Body:

json

{
  "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

json

{
  "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

json

{
  "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

Endpoint: POST /api/v2.1/verifications/{verificationId}/documents

Content-Type: application/json

Headers:

http

Authorization: Bearer {jwt-token}
Content-Type: application/json

Request Body:

json

{
  "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 content
documentCategory: Use VERIFICATION for KYB documents
customerId: Organization ID (from verification initiation)

Status: 201 Created

json

{
  "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

json

{
  "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

flowchart LR
    A[INITIATED] --> B[IN_PROGRESS]
    B --> C[PENDING_REVIEW]
    C --> D[UNDER_REVIEW]
    D --> E{Decision}
    E -->|Approved| F[APPROVED]
    E -->|Rejected| G[REJECTED]
    E -->|More Info| H[ADDITIONAL_INFO_REQUIRED]
    H --> B

Approve Verification (Admin)

Endpoint: POST /api/v2.1/verifications/{verificationId}/approve

Headers:

http

Authorization: Bearer {admin-jwt-token}
X-User-ID: admin-user-id
X-User-Roles: COMPLIANCE_OFFICER

Request Body:

json

{
  "adminNotes": "All documents verified. Organization identity confirmed.",
  "approvedBy": "ADMIN_USER",
  "approvalReason": "All documents verified for organization customer"
}

Status: 200 OK

json

{
  "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