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:

Phase	Endpoint	Time	Prerequisites	Status After
1. Categorization	`GET /customer/individual/categorization/hierarchy/{tenantId}`	< 1 min	API credentials	Category selected
2. Registration	`POST /registration`	< 5 min	Category ID, org details	Organization created
3. Personnel	`POST /{orgId}/employee`, `/director`, `/shareholders`	20 min	Organization ID	All roles filled
4. Documents	`POST /{orgId}/documents`	10 min	Corporate docs ready	Documents uploaded
5. Verification	`POST /{orgId}/verification`	2-5 days	All docs + personnel	KYB submitted
6. Consents	`POST /{orgId}/consents/*`	5 min	Legal representative	All 3 consents accepted
7. Activation	`POST /{orgId}/activation`	Instant	All above complete	Organization ACTIVE, wallet ACTIVE
8. Operations	Financial APIs	Ongoing	Activated account	Transfers, 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: 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

Registration

Management

Add directors, shareholders, and employees (ADMIN_USER required)

Verification

Complete KYB verification

Consents

Accept required business consents

Activation

Activate organization account

Prerequisites Before Starting

Organization Lifecycle Flow

Key Differences: B2C vs B2B

Aspect	Individual Customer (B2C)	Organization Customer (B2B)
Registration	Single person	Company + personnel
Verification	KYC (identity)	KYB (business + UBO)
Personnel	N/A	Directors, shareholders, employees required
Ownership	N/A	Must declare 100% ownership
Roles	User only	ADMIN_USER, COMPLIANCE_OFFICER, etc.
Approval	TENANT_ADMIN	POWER_TENANT for high-risk
Time	1-3 days	2-5 days
Complexity	Simple	Complex (multi-step)

Personnel Management Rules

Required Roles

Role	Minimum Required	Purpose	Can Activate Account
ADMIN_USER	1	Full organization access	✅ Yes
COMPLIANCE_OFFICER	0 (recommended 1)	Approve verifications	✅ Yes
Director	1	Corporate governance	No
Shareholder	1+ (100% total)	Ownership structure	No

Order of Operations

IMPORTANT: Add personnel in this exact order:

Employee (with ADMIN_USER role) - MUST BE FIRST!
Director (minimum 1)
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

Version	Date	Changes
v1.0	2026-01-13	Enhanced organization customer API overview

Individual Activation Organization Registration

⌘I

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

Organization Customer APIs (B2B)

Organization Customer APIs (B2B)

Complete Organization Journey

Quick Start Guide

Step 1: Register Organization

Step 2: Add Personnel (Order Matters!)

Step 3-7: Complete Flow

API Endpoints by Phase

Registration

Management

Verification

Consents

Activation

Prerequisites Before Starting

Organization Lifecycle Flow

Key Differences: B2C vs B2B

Personnel Management Rules

Required Roles

Order of Operations

Standard Headers

API Schema Mapping

Individual APIs

Financial Operations

Changelog

​Organization Customer APIs (B2B)

​Complete Organization Journey

​Quick Start Guide

​Step 1: Register Organization

​Step 2: Add Personnel (Order Matters!)

​Step 3-7: Complete Flow

​API Endpoints by Phase

Registration

Management

Verification

Consents

Activation

​Prerequisites Before Starting

​Organization Lifecycle Flow

​Key Differences: B2C vs B2B

​Personnel Management Rules

​Required Roles

​Order of Operations

​Related Resources

Standard Headers

API Schema Mapping

Individual APIs

Financial Operations

​Changelog

Organization Customer APIs (B2B)

Complete Organization Journey

Quick Start Guide

Step 1: Register Organization

Step 2: Add Personnel (Order Matters!)

Step 3-7: Complete Flow

API Endpoints by Phase

Prerequisites Before Starting

Organization Lifecycle Flow

Key Differences: B2C vs B2B

Personnel Management Rules

Required Roles

Order of Operations

Related Resources

Changelog