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

# Customer Onboarding & KYC

> Personal and Corporate CIF generation, CBN KYC Tiers 1–3, BVN/NIN checks, CAC RC registration, and CABAL management.

Customer onboarding in Nucleus is governed by Central Bank of Nigeria (CBN) Anti-Money Laundering (AML/CFT) and Customer Due Diligence regulations.

Nucleus provides a **unified Customer Information File (CIF)** architecture: whether an account is opened for an individual person or a multinational corporate entity, the engine derives a single, immutable CIF that binds all associated savings, fixed deposits, credit lines, and signatories.

## Key Rules & Architectural Invariants

<Warning>
  **Branch Scoping Rule:** All customers (Individual and Corporate) must be onboarded at an operating branch (`officeId >= 2`), not the Head Office. Head Office is reserved for corporate governance, audit, compliance, and treasury policy.
</Warning>

***

## 1. Personal Accounts (`legalFormId: 1`)

Personal customers require individual identity data, BVN validation, and KYC Tier classification.

### Onboarding Request:

```bash theme={null}
POST /nucleus/api/v1/clients?tenantIdentifier=pilot-mfb
Content-Type: application/json

{
  "officeId": 2,
  "firstname": "Amina",
  "lastname": "Danladi",
  "externalId": "CUST-00912",
  "staffId": 14,
  "dateFormat": "dd MMMM yyyy",
  "locale": "en",
  "active": true,
  "activationDate": "12 September 2026",
  "legalFormId": 1
}
```

### Response:

```json theme={null}
{
  "officeId": 2,
  "clientId": 2,
  "resourceId": 2,
  "changes": {
    "cif": "CIF00000002",
    "accountNo": "000000002"
  }
}
```

***

## 2. Corporate Accounts (`legalFormId: 2`)

Corporate entities (Limited Liability Companies, Public Limited Companies, Partnerships, Sole Proprietorships, NGOs, Cooperatives) follow the **exact same unified CIF process**, while also capturing corporate registry data:

### Corporate Entity Parameters:

* **`legalFormId`:** Set to `2` (Entity / Non-Person).
* **`fullname`:** The registered legal business name (e.g. `Dangote Flour Mills Ltd`).
* **`clientNonPersonDetails`:**
  * `incorpNumber`: Corporate Affairs Commission (CAC) Registration number (e.g. `RC-1294812`).
  * `constitutionId`: Legal entity type (Code `200200` to `200207`).
  * `mainBusinessLineId`: Industry classification sector (Code `200220` to `200232`).
  * `incorpValidityTillDate`: Certificate validity / re-registration deadline.
  * `remarks`: Line of business summary or KYC notes.
  * `scumlNumber`: Special Control Unit Against Money Laundering registration (mandatory for DNFBPs).

### Supported Legal Constitutions:

| Constitution Code | Legal Entity Type                                  |
| ----------------- | -------------------------------------------------- |
| `200200`          | Sole Proprietorship (Business Name)                |
| `200201`          | Partnership                                        |
| `200202`          | Private Limited Company (Ltd)                      |
| `200203`          | Public Limited Company (PLC)                       |
| `200204`          | Company Limited by Guarantee                       |
| `200205`          | Incorporated Trustees (NGO / Association / Church) |
| `200206`          | Cooperative Society                                |
| `200207`          | Government Agency / Parastatal                     |

### Corporate Onboarding Request:

```bash theme={null}
POST /nucleus/api/v1/clients?tenantIdentifier=pilot-mfb
Content-Type: application/json

{
  "officeId": 2,
  "fullname": "Dangote Flour Mills Ltd",
  "externalId": "CORP-001",
  "dateFormat": "dd MMMM yyyy",
  "locale": "en",
  "active": true,
  "activationDate": "12 September 2026",
  "legalFormId": 2,
  "clientNonPersonDetails": {
    "constitutionId": 200202,
    "mainBusinessLineId": 200221,
    "incorpNumber": "RC-1294812",
    "incorpValidityTillDate": "12 September 2035",
    "remarks": "Food and Consumer Goods Manufacturing",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }
}
```

### Corporate Response:

```json theme={null}
{
  "officeId": 2,
  "clientId": 3,
  "resourceId": 3,
  "changes": {
    "cif": "CIF00000003",
    "accountNo": "000000003"
  },
  "resourceExternalId": "CORP-001"
}
```

<Note>
  Notice that `Dangote Flour Mills Ltd` is issued **`CIF00000003`** through the exact same automated CIF generator. All corporate accounts (operating current accounts, collection accounts, FX accounts, and credit facilities) bind to this single corporate CIF.
</Note>

***

## 3. Corporate KYC Requirements & Compliance Checklist

Under Central Bank of Nigeria (CBN) AML/CFT Regulations and Customer Due Diligence guidelines, onboarding a corporate entity requires specific documentation and verified corporate officials before commercial accounts can be activated.

### Mandatory Corporate Documents:

1. **CAC Registration:** Certificate of Incorporation and CAC Status Report (details of registered office, objects, directors, and share capital).
2. **Constitutional Documents:** Certified Memorandum & Articles of Association (MEMART) or Partnership Deed / Constitution.
3. **Board Resolution:** Duly signed resolution authorizing the opening of the account and designating authorized signatories.
4. **Tax Identification Number (TIN):** Mandatory corporate tax ID issued by the Federal Inland Revenue Service (FIRS) / JTB.
5. **SCUML Certificate:** Mandatory for Designated Non-Financial Businesses and Professions (DNFBPs)—such as real estate developers, car dealers, legal practitioners, audit firms, hotels, and casinos.
6. **Ultimate Beneficial Ownership (UBO):** Full disclosure of all natural persons who ultimately own or control $\ge 5\%$ of shares, voting rights, or executive authority.
7. **Signatories & Directors Due Diligence:** BVN, NIN, government-issued photo ID, and passport photograph for all authorized signatories and directors.
8. **Two (2) Independent Bank References:** Mandated by CBN for all current accounts (personal and corporate).
9. **Physical Address Verification:** Certified utility bill and physical visitation report.

***

## 4. Setting Corporate TIN & SCUML

Corporate KYC attributes (TIN and SCUML certificate details) are configured via the Corporate KYC endpoint:

```bash theme={null}
PUT /nucleus/api/v1/clients/{clientId}/corporatekyc
Nucleus-Platform-TenantId: pilot-mfb
Content-Type: application/json

{
  "tin": "10982347-0001",
  "scumlNumber": "SC-1204918-LA",
  "scumlExpiry": "2029-09-12"
}
```

***

## 5. Adding Corporate Officials (Directors, Signatories, UBOs)

CBN guidelines mandate recording every person with management control, signing authority, or significant ownership:

```bash theme={null}
POST /nucleus/api/v1/clients/{clientId}/officials
Nucleus-Platform-TenantId: pilot-mfb
Content-Type: application/json

{
  "officialType": "BENEFICIAL_OWNER",
  "name": "Aliko Dangote",
  "bvn": "22212345678",
  "tin": "10023456",
  "ownershipPct": 75.0,
  "phone": "+2348030000001",
  "email": "aliko@dangote.com"
}
```

Supported `officialType` values:

* `DIRECTOR`: Statutory board member listed on CAC Status Report.
* `SIGNATORY`: Authorized mandate holder (Class A / Class B).
* `BENEFICIAL_OWNER`: Natural person holding $\ge 5\%$ equity or controlling interest.

***

## 6. Current Account 2-Referee Mandate Enforcement

<Warning>
  **CBN Current Account Rule:** Any deposit account configured with overdraft capability or designated as a Current Account requires **at least two (2) verified bank references** on file. Attempting to activate an account with fewer than 2 references will return `403 Forbidden` (`error.msg.savingsaccount.current.references.required`).
</Warning>

### Adding Referees:

```bash theme={null}
POST /nucleus/api/v1/savingsaccounts/{savingsAccountId}/references
Nucleus-Platform-TenantId: pilot-mfb
Content-Type: application/json

{
  "refereeName": "Zenith Bank Plc",
  "refereeAccountNo": "1012345678",
  "refereeBank": "057",
  "refereePhone": "+23412787000",
  "refereeEmail": "references@zenithbank.com",
  "refereeAddress": "Plot 84, Ajose Adeogun, VI, Lagos",
  "relationship": "Commercial Banker for 10 years"
}
```

Once two references are registered, the account can be activated via:

```bash theme={null}
POST /nucleus/api/v1/savingsaccounts/{savingsAccountId}?command=activate
```

***

## 7. CBN KYC Tiers

Nucleus natively enforces transaction and balance limits across the 3 CBN KYC tiers:

| Tier                                | Maximum Single Deposit | Maximum Cumulative Balance | Requirements                                                      |
| ----------------------------------- | ---------------------- | -------------------------- | ----------------------------------------------------------------- |
| **Tier 1 (Low Value)**              | ₦50,000                | ₦300,000                   | Basic personal info, passport photograph, phone number            |
| **Tier 2 (Medium Value)**           | ₦100,000               | ₦500,000                   | Verified BVN, national identity card (NIN), proof of address      |
| **Tier 3 (High Value / Corporate)** | Unlimited              | Unlimited                  | Corporate entity status, full CAC documents, TIN, UBO, 2 referees |

Corporate entities (`legalFormId: 2`) are automatically classified as **Tier 3** upon onboarding, allowing unlimited corporate transaction volumes.

***

## 8. The Relationship Officer's CABAL Book

In Nigerian banking operations, the **CABAL** refers to an Account Officer's or Relationship Manager's assigned customer book:

* **Account Officer (Role `320013`):** Scoped strictly to their own assigned portfolio (`staffId`). They can view, track deposit mobilization, and manage loan appraisals for customers in their CABAL.
* **Head Office & Branch Managers:** Can inspect the consolidated customer base or view the CABAL broken down by branch, account type, and relationship officer.