> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  **Base URL:** `https://sandbox.finhub.cloud/api/v2.1/customer/organization`
</Info>

<Note>
  For complete details on authentication and headers, refer to the [Standard HTTP Headers](../schemas/standard-headers) reference documentation.
</Note>

<Note>
  **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").
</Note>

***

## 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

```bash theme={null}
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!)

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Registration" icon="building-circle-check" href="/baas/api/reference/customer-apis/organization/registration">
    Register new business organizations
  </Card>

  <Card title="Management" icon="users-gear" href="/baas/api/reference/customer-apis/organization/management">
    Add directors, shareholders, and employees (ADMIN\_USER required)
  </Card>

  <Card title="Verification" icon="shield-check" href="/baas/api/reference/verification-compliance/verification-management">
    Complete KYB verification
  </Card>

  <Card title="Consents" icon="file-signature" href="/baas/api/reference/customer-apis/organization/consents">
    Accept required business consents
  </Card>

  <Card title="Activation" icon="circle-check" href="/baas/api/reference/customer-apis/organization/activation">
    Activate organization account
  </Card>
</CardGroup>

***

## 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

```mermaid theme={null}
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

| 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

<Warning>
  **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.
</Warning>

***

## Related Resources

<CardGroup cols={2}>
  <Card title="Standard Headers" icon="list" href="../schemas/standard-headers">
    Required HTTP headers for all endpoints
  </Card>

  <Card title="API Schema Mapping" icon="code" href="../../../../doc/mint/API_SCHEMA_MAPPING">
    Complete OpenAPI specifications
  </Card>

  <Card title="Individual APIs" icon="user" href="../individual">
    B2C customer management
  </Card>

  <Card title="Financial Operations" icon="money-bill-transfer" href="../../financial-operations">
    Wallet and payment operations
  </Card>
</CardGroup>

***

## Changelog

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