> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 theme={null}
X-User-ID: user-660e8400-e29b-41d4-a716-446655440011
X-User-Roles: COMPLIANCE_OFFICER
Authorization: Bearer {jwt-token}
```
**Request Body:**
```json theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"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}/documents`
**Content-Type:** `application/json`
**Headers:**
```http theme={null}
Authorization: Bearer {jwt-token}
Content-Type: application/json
```
**Request Body:**
```json theme={null}
{
"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 theme={null}
{
"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 theme={null}
{
"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
```mermaid theme={null}
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 theme={null}
Authorization: Bearer {admin-jwt-token}
X-User-ID: admin-user-id
X-User-Roles: COMPLIANCE_OFFICER
```
**Request Body:**
```json theme={null}
{
"adminNotes": "All documents verified. Organization identity confirmed.",
"approvedBy": "ADMIN_USER",
"approvalReason": "All documents verified for organization customer"
}
```
**Status:** `200 OK`
```json theme={null}
{
"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**.
Accept organization-level consents