URL: /baas/api/reference/customer-apis/organization

---
title: 'Organization Customer APIs (B2B)'
description: '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
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
# 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-round" 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/verification-compliance/consents-organization">
    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
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="banknote" href="../../financial-operations">
    Wallet and payment operations
  </Card>
</CardGroup>

---

## Changelog

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