Skip to main content

​
Organization Customer APIs (B2B)

Complete API reference for business organization lifecycle management, from registration through corporate structure setup, verification, and activation.
Base URL: https://sandbox.finhub.cloud/api/v2.1/customer/organization
For complete details on authentication and headers, refer to the Standard HTTP Headers reference documentation.
Categorization: Use GET /customer/individual/categorization/hierarchy/{tenantId} to retrieve all available categories. Filter the response for organization-suitable categories (categoryName contains “BUSINESS”, “ORGANIZATION”, or “B2B”).

​
Complete Organization Journey

The organization onboarding flow consists of 8 phases:
PhaseEndpointTimePrerequisitesStatus After
1. CategorizationGET /customer/individual/categorization/hierarchy/{tenantId}< 1 minAPI credentialsCategory selected
2. RegistrationPOST /registration< 5 minCategory ID, org detailsOrganization created
3. PersonnelPOST /{orgId}/employee, /director, /shareholders20 minOrganization IDAll roles filled
4. DocumentsPOST /{orgId}/documents10 minCorporate docs readyDocuments uploaded
5. VerificationPOST /{orgId}/verification2-5 daysAll docs + personnelKYB submitted
6. ConsentsPOST /{orgId}/consents/*5 minLegal representativeAll 3 consents accepted
7. ActivationPOST /{orgId}/activationInstantAll above completeOrganization ACTIVE, wallet ACTIVE
8. OperationsFinancial APIsOngoingActivated accountTransfers, payments enabled
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: YOUR_TENANT_ID" \
  -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

Registration

Register new business organizations

Management

Add directors, shareholders, and employees (ADMIN_USER required)

Verification

Complete KYB verification

Consents

Accept required business consents

Activation

Activate organization account

Documents

Upload corporate documents

​
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

​
Key Differences: B2C vs B2B

AspectIndividual Customer (B2C)Organization Customer (B2B)
RegistrationSingle personCompany + personnel
VerificationKYC (identity)KYB (business + UBO)
PersonnelN/ADirectors, shareholders, employees required
OwnershipN/AMust declare 100% ownership
RolesUser onlyADMIN_USER, COMPLIANCE_OFFICER, etc.
ApprovalTENANT_ADMINPOWER_TENANT for high-risk
Time1-3 days2-5 days
ComplexitySimpleComplex (multi-step)

​
Personnel Management Rules

​
Required Roles

RoleMinimum RequiredPurposeCan Activate Account
ADMIN_USER1Full organization access✅ Yes
COMPLIANCE_OFFICER0 (recommended 1)Approve verifications✅ Yes
Director1Corporate governanceNo
Shareholder1+ (100% total)Ownership structureNo

​
Order of Operations

IMPORTANT: Add personnel in this exact order:
  1. Employee (with ADMIN_USER role) - MUST BE FIRST!
  2. Director (minimum 1)
  3. Shareholders (must total 100%)
Attempting to activate without an ADMIN_USER will fail with a 400 error.

Standard Headers

Required HTTP headers for all endpoints

API Schema Mapping

Complete OpenAPI specifications

Individual APIs

B2C customer management

Financial Operations

Wallet and payment operations

​
Changelog

VersionDateChanges
v1.02026-01-13Enhanced organization customer API overview