Organization Customer APIs (B2B)

Complete API reference for business organization lifecycle management, from registration through corporate structure setup, verification, and activation.

Complete Organization Journey

The organization onboarding flow consists of 8 phases:

Total Time: 2-5 business days (mostly KYB verification wait time)

Quick Start Guide

Step 1: Register Organization

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/organization/registration" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Content-Type: application/json" \
  -d '{ "legalName": "Acme Corp", "categoryId": "cat_business_123", ... }'

Step 2: Add Personnel (Order Matters!)

# 1. Add Employee with ADMIN_USER role (REQUIRED FIRST)
POST /{orgId}/employee { "roles": ["ADMIN_USER"], ... }

# 2. Add Director (minimum 1)
POST /{orgId}/director { ... }

# 3. Add Shareholders (must total 100%)
POST /{orgId}/shareholders [{ "ownershipPercentage": 60 }, { "ownershipPercentage": 40 }]

Step 3-7: Complete Flow

See individual endpoint documentation below.

API Endpoints by Phase

Prerequisites Before Starting

• API credentials obtained (Tenant ID, API keys)
• Business categorization selected (risk level)
• Corporate documents ready:
  • Certificate of Incorporation
  • Articles of Association
  • Shareholder Register
  • Director IDs
  • Bank Statements (last 3 months)
• Personnel information collected:
  • At least 1 employee (with ADMIN_USER role)
  • At least 1 director
  • All shareholders (must total 100% ownership)

Organization Lifecycle Flow

stateDiagram-v2
    [*] --> Categorization: Get business categories
    Categorization --> Registration: Select category
    Registration --> AddEmployee: Create organization
    AddEmployee --> AddDirector: ADMIN_USER added
    AddDirector --> AddShareholders: Min 1 director
    AddShareholders --> Documents: 100% ownership
    Documents --> Verification: Upload corp docs
    Verification --> Consents: Submit KYB
    Consents --> Activation: Accept all 3
    Activation --> [*]: Organization ACTIVE
    
    note right of AddEmployee
        MUST be first!
        Requires ADMIN_USER role
    end note
    
    note right of Verification
        2-5 days wait time
        POWER_TENANT approval
        for high-risk businesses
    end note
    
    note right of Activation
        Prerequisites:
        - All personnel verified
        - All consents accepted
        - KYB approved
        - Documents verified
    end note

Key Differences: B2C vs B2B

Personnel Management Rules

Required Roles

Order of Operations

Related Resources

Changelog