Organization Verification (KYB)

Complete Know Your Business (KYB) verification process for business organizations, including document verification, personnel checks, and beneficial owner identification.

Base URL: https://sandbox.finhub.cloud

For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.

Verification Levels

Level	Description	Approval Required	Typical Use Case
TENANT_VERIFIED	Basic business verification	TENANT_ADMIN	Standard businesses, low-risk sectors
POWER_TENANT_VERIFIED	Enhanced due diligence	POWER_TENANT (Super Admin)	High-risk businesses, large transactions, PEPs

High-Risk Organizations require POWER_TENANT_VERIFIED level:

Money service businesses
Cryptocurrency exchanges
Gambling/gaming businesses
Organizations with PEP directors or beneficial owners
Organizations from high-risk jurisdictions

Complete KYB Verification Flow

Step 1: Initiate Verification

Check what verification is required for the organization. Endpoint: GET /api/v2.1/customer/organization/{organizationId}/verification/requirements

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/requirements" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Forwarded-For: 203.0.113.42" \
  -H "User-Agent: MyApp/1.0"

Response:

{
  "success": true,
  "data": {
    "organizationId": "org_12345",
    "verificationLevel": "TENANT_VERIFIED",
    "requiredDocuments": [
      "CERTIFICATE_OF_INCORPORATION",
      "ARTICLES_OF_ASSOCIATION",
      "SHAREHOLDER_REGISTER",
      "DIRECTOR_ID",
      "BENEFICIAL_OWNER_DECLARATION",
      "BANK_STATEMENT"
    ],
    "requiredPersonnelVerification": {
      "directors": {
        "minimum": 1,
        "requireIdVerification": true,
        "requirePepCheck": true
      },
      "beneficialOwners": {
        "minimum": 1,
        "ownershipThreshold": 25.0,
        "requireIdVerification": true,
        "requirePepCheck": true
      }
    },
    "estimatedReviewTime": "2-5 business days"
  }
}

Step 2: Submit Verification Documents

Upload required documents to the verification process. Endpoint: POST /api/v2.1/verifications/{verificationId}/documents

Use the verification ID returned from Step 1. Documents are uploaded as JSON with base64-encoded content.

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/verifications/ver_12345/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 203.0.113.42" \
  -H "User-Agent: MyApp/1.0" \
  -d '{
    "docId": "550e8400-e29b-41d4-a716-446655440000",
    "documentType": "CERTIFICATE_OF_INCORPORATION",
    "fileName": "incorporation_cert.pdf",
    "fileContent": "JVBERi0xLjQKJeLjz9MKNyAwIG9iaiA8PAovVHlwZSAvQ2F0YWxvZy...",
    "customerId": "org_12345",
    "description": "Company registration certificate"
  }'

Request Body:

Field	Type	Required	Description
`docId`	string (UUID)	Yes	Unique document identifier (generate using UUID v4)
`documentType`	string	Yes	Document type from the table below
`fileName`	string	Yes	Original file name with extension (.pdf, .jpg, .png)
`fileContent`	string	Yes	Base64-encoded file content
`customerId`	string	Yes	Organization ID from registration
`description`	string	No	Document purpose or description

Response:

{
  "success": true,
  "data": {
    "documentId": "doc_67890",
    "verificationId": "ver_12345",
    "status": "UPLOADED",
    "uploadedAt": "2026-01-13T10:30:00Z"
  }
}

Required Documents:

Document Type	Value for `documentType`	Required For	Description
Certificate of Incorporation	`CERTIFICATE_OF_INCORPORATION`	All	Proof of company registration
Articles of Association	`ARTICLES_OF_ASSOCIATION`	All	Company bylaws/constitution
Proof of Registered Address	`PROOF_OF_REGISTERED_ADDRESS`	All	Registered office address proof
Beneficial Owners Declaration	`BENEFICIAL_OWNERS_DECLARATION`	All	UBO form (25%+ ownership)
Bank Statement	`BANK_STATEMENT`	All	Last 3 months business statements
Director IDs	`DIRECTOR_ID`	All	Passport/ID for each director
Financial Statements	`FINANCIAL_STATEMENTS`	Large businesses	Audited accounts (revenue > €1M)
Business License	`BUSINESS_LICENSE`	Regulated sectors	Industry-specific licenses

File Requirements:

Formats: PDF, JPG, PNG
Maximum size: 10MB per file
Base64 encoding required for JSON upload
Use UTF-8 encoding for file names

Step 3: Personnel Verification Check

Ensure all required personnel are added and verified: Endpoint: GET /api/v2.1/customer/organization/{organizationId}/verification/personnel-status

cURL

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/personnel-status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Response:

{
  "success": true,
  "data": {
    "directors": {
      "total": 2,
      "verified": 2,
      "pending": 0,
      "status": "COMPLETE"
    },
    "beneficialOwners": {
      "total": 2,
      "verified": 2,
      "totalOwnership": 100.0,
      "status": "COMPLETE"
    },
    "employees": {
      "total": 5,
      "withAdminRole": 1,
      "status": "COMPLETE"
    },
    "overallStatus": "READY_FOR_VERIFICATION"
  }
}

Step 4: Submit Verification Request

Once all documents and personnel are in place, submit for verification. Endpoint: POST /api/v2.1/customer/organization/{organizationId}/verification Request Body:

{
  "verificationType": "KYB",
  "verificationLevel": "TENANT_VERIFIED",
  "priority": "NORMAL",
  "verificationData": {
    "businessPurpose": "Import/export of electronic goods",
    "expectedAnnualRevenue": "€500,000 - €1,000,000",
    "expectedTransactionVolume": "50-100 transactions/month",
    "sourceOfFunds": "Business revenue and investor capital",
    "primaryJurisdictions": ["DE", "FR", "NL"]
  }
}

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Forwarded-For: 203.0.113.42" \
  -H "User-Agent: MyApp/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "verificationType": "KYB",
    "verificationLevel": "TENANT_VERIFIED",
    "priority": "NORMAL",
    "verificationData": {
      "businessPurpose": "Import/export of electronic goods",
      "expectedAnnualRevenue": "€500,000 - €1,000,000"
    }
  }'

Response (200 OK):

{
  "success": true,
  "data": {
    "verificationId": "ver_org_67890",
    "organizationId": "org_12345",
    "status": "PENDING_REVIEW",
    "type": "KYB",
    "level": "TENANT_VERIFIED",
    "submittedAt": "2024-01-15T10:30:00Z",
    "estimatedCompletionTime": "2-5 business days",
    "requiredDocuments": [
      {
        "documentType": "CERTIFICATE_OF_INCORPORATION",
        "status": "SUBMITTED",
        "submittedAt": "2024-01-15T09:00:00Z"
      },
      {
        "documentType": "ARTICLES_OF_ASSOCIATION",
        "status": "SUBMITTED",
        "submittedAt": "2024-01-15T09:15:00Z"
      }
    ],
    "personnelChecks": {
      "directors": "COMPLETE",
      "beneficialOwners": "COMPLETE",
      "pepScreening": "IN_PROGRESS"
    },
    "nextSteps": [
      "Wait for compliance review",
      "PEP and sanctions screening in progress",
      "You will be notified via email when verification is complete"
    ]
  }
}

Step 5: Check Verification Status

Poll for verification status updates. Endpoint: GET /api/v2.1/customer/organization/{organizationId}/verification/status

curl -X GET "https://sandbox.finhub.cloud/api/v2.1/customer/organization/org_12345/verification/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Response (Approved):

{
  "success": true,
  "data": {
    "verificationId": "ver_org_67890",
    "organizationId": "org_12345",
    "status": "APPROVED",
    "type": "KYB",
    "level": "TENANT_VERIFIED",
    "submittedAt": "2024-01-15T10:30:00Z",
    "reviewedAt": "2024-01-17T14:20:00Z",
    "approvedAt": "2024-01-17T14:20:00Z",
    "reviewedBy": "compliance_officer_01",
    "approvalRequired": "TENANT_ADMIN",
    "verificationChecks": {
      "documentsVerified": true,
      "directorsVerified": true,
      "beneficialOwnersVerified": true,
      "pepScreening": "CLEAR",
      "sanctionsScreening": "CLEAR",
      "adverseMediaScreening": "CLEAR"
    },
    "reviewNotes": "All documents verified. Business purpose and structure validated. No adverse findings.",
    "nextSteps": [
      "Proceed to consent acceptance",
      "Then activate organization"
    ]
  }
}

Verification Status Flow

Status Descriptions

Status	Description	Next Action
NOT_STARTED	Documents/personnel not yet submitted	Upload documents, add personnel
PREPARING	Documents being uploaded	Complete all uploads, then submit
PENDING_REVIEW	Submitted, queued for review	Wait for compliance officer
UNDER_REVIEW	Being reviewed by compliance	Wait for decision (2-5 days)
ADDITIONAL_INFO_REQUIRED	More information needed	Provide requested information
APPROVED	Verification successful	Proceed to consent & activation
REJECTED	Verification failed	Review reasons, fix issues, resubmit

Step 6: Verification Approval (Admin)

For organizations requiring TENANT_ADMIN or POWER_TENANT approval. Endpoint: POST /api/v2.1/customer/organization/{organizationId}/verification/approve Required Role: COMPLIANCE_OFFICER or ADMIN_USER Request:

{
  "verificationId": "ver_org_67890",
  "approved": true,
  "approvalNotes": "All KYB checks completed successfully. Documents verified. PEP and sanctions screening clear.",
  "conditions": []
}

Response:

{
  "success": true,
  "data": {
    "verificationId": "ver_org_67890",
    "status": "APPROVED",
    "approvedAt": "2024-01-17T14:20:00Z",
    "approvedBy": "compliance_officer_01",
    "nextSteps": [
      "Organization is now verified",
      "Proceed to consent acceptance",
      "Then activate organization"
    ]
  }
}

UBO (Ultimate Beneficial Owner) Requirements

Organizations must declare all UBOs (individuals owning ≥25% of the company).

UBO Verification Checklist

All shareholders with ≥25% ownership declared
Each UBO has submitted ID verification
PEP screening completed for all UBOs
Sanctions screening completed for all UBOs
Source of wealth documented for UBOs
Control structure diagram uploaded (if complex)

Complex Ownership Structures

For organizations with multi-tier ownership (e.g., Company A owns Company B):

Upload ownership structure diagram
Declare all natural persons with ≥25% indirect ownership
Provide incorporation documents for parent companies
Complete enhanced due diligence for all layers

Response Codes

Code	Description
`200`	Verification status retrieved successfully
`201`	Verification submitted successfully
`400`	Missing required documents or personnel
`403`	Insufficient permissions
`404`	Organization not found
`422`	Verification prerequisites not met
`500`	Internal server error

Common Verification Errors

Error: Missing Required Documents

Problem: Not all required documents uploaded Solution: Check verification requirements and upload all documents:

GET /api/v2.1/customer/organization/{orgId}/verification/requirements

Error: Ownership Validation Failed

Problem: Shareholder ownership doesn’t total 100% Solution: Ensure all shareholders are declared and ownership percentages sum to exactly 100%.

Error: Missing Admin User

Problem: No employee with ADMIN_USER role Solution: Add at least one employee with ADMIN_USER role before submitting verification.

Error: Director Not Verified

Problem: One or more directors missing ID verification Solution: Ensure all directors have submitted valid identification documents.

API Schema Reference

For the complete OpenAPI schema specification, see the API Schema Mapping documentation (Organization Verification operation - to be added).

Standard Headers

Complete HTTP headers reference

Documents

Upload verification documents

Management

Add directors, employees, shareholders

Consents

Accept organization consents

Activation

Activate verified organization

Individual Verification

Individual KYC verification

Changelog

Version	Date	Changes
v1.0	2026-01-13	Initial organization verification documentation

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Organization Verification (KYB)

Organization Verification (KYB)

Verification Levels

Complete KYB Verification Flow

Step 1: Initiate Verification

Step 2: Submit Verification Documents

Step 3: Personnel Verification Check

Step 4: Submit Verification Request

Step 5: Check Verification Status

Verification Status Flow

Status Descriptions

Step 6: Verification Approval (Admin)

UBO (Ultimate Beneficial Owner) Requirements

UBO Verification Checklist

Complex Ownership Structures

Response Codes

Common Verification Errors

Error: Missing Required Documents

Error: Ownership Validation Failed

Error: Missing Admin User

Error: Director Not Verified

API Schema Reference

Standard Headers

Documents

Management

Consents

Activation

Individual Verification

Changelog

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Organization Verification (KYB)

​Verification Levels

​Complete KYB Verification Flow

​Step 1: Initiate Verification

​Step 2: Submit Verification Documents

​Step 3: Personnel Verification Check

​Step 4: Submit Verification Request

​Step 5: Check Verification Status

​Verification Status Flow

​Status Descriptions

​Step 6: Verification Approval (Admin)

​UBO (Ultimate Beneficial Owner) Requirements

​UBO Verification Checklist

​Complex Ownership Structures

​Response Codes

​Common Verification Errors

​Error: Missing Required Documents

​Error: Ownership Validation Failed

​Error: Missing Admin User

​Error: Director Not Verified

​API Schema Reference

​Related Endpoints

Standard Headers

Documents

Management

Consents

Activation

Individual Verification

​Changelog

Organization Verification (KYB)

Verification Levels

Complete KYB Verification Flow

Step 1: Initiate Verification

Step 2: Submit Verification Documents

Step 3: Personnel Verification Check

Step 4: Submit Verification Request

Step 5: Check Verification Status

Verification Status Flow

Status Descriptions

Step 6: Verification Approval (Admin)

UBO (Ultimate Beneficial Owner) Requirements

UBO Verification Checklist

Complex Ownership Structures

Response Codes

Common Verification Errors

Error: Missing Required Documents

Error: Ownership Validation Failed

Error: Missing Admin User

Error: Director Not Verified

API Schema Reference

Related Endpoints

Changelog