Organization Customer APIs (B2B)

APIs for managing business organization lifecycle

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

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

---

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

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:

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.

---

Related Resources

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