Cosmic Module

O

Qubits of DPK

March 20, 2026

Core Open Source

The Analogy

A Client in Fineract is like a customer file at a bank. When you walk into a bank for the first time, they create a file for you with your name, photo ID, address. Everything you do — open a savings account, take a loan — is linked to that file. The "Client" is that file.

What is a Client?

A Client is the person or entity that the bank serves. They can be:
  • Individual (Person): A person with a name, date of birth, gender
  • Entity (Business): A company or organisation (legalFormId = 2)

Client Status State Machine

javascript
QUBITS OF DPK
1PENDING (100) ──activate──▶ ACTIVE (300)
2     |                              |
3   reject                         close
4     |                              |
5     ▼                              ▼
6 REJECTED (500)               CLOSED (600)
7                                    |
8                               reactivate
9                                    |
10                                    ▼
11                              PENDING (100)

Creating a Client

API Call

javascript
QUBITS OF DPK
1POST /fineract-provider/api/v1/clients
2Body: {
3  "officeId": 1,
4  "legalFormId": 1,          // 1=Person, 2=Entity
5  "firstname": "Deepak",
6  "lastname": "Kumar",
7  "externalId": "DK-2025-001",  // YOUR system's ID
8  "active": true,
9  "activationDate": "01 March 2025",
10  "dateFormat": "dd MMMM yyyy",
11  "locale": "en"
12}

Code Flow

javascript
QUBITS OF DPK
1ClientApiResource.create()
2  → CreateClientCommandHandler.handle()
3      → ClientWritePlatformServiceImpl.createClient()
4          → Validates officeId, firstname/lastname not empty
5          → Validates externalId is unique (if provided)
6          → Creates Client entity
7          → If active=true: sets status=ACTIVE directly (skips PENDING)
8          → Saves to m_client
9          → Publishes ClientCreatedBusinessEvent

DB Table: m_client

sql
QUBITS OF DPK
1CREATE TABLE m_client (
2    id                    BIGINT PRIMARY KEY,
3    office_id             BIGINT,        -- which branch
4    external_id           VARCHAR(100),  -- your system's ID
5    display_name          VARCHAR(100),  -- "Deepak Kumar"
6    firstname             VARCHAR(50),
7    lastname              VARCHAR(50),
8    status_enum           INT,           -- 100/300/600
9    activation_date       DATE,
10    submittedon_date      DATE,
11    legal_form_enum       INT,           -- 1=Person, 2=Entity
12    mobile_no             VARCHAR(50)
13);

External ID — The Key Feature (Your PR #5659!)

Why It Exists

When integrating Fineract with another system:
  • Your CRM has customer ID: CRM-12345
  • Fineract has internal ID: 42
  • Problem: you have to maintain a mapping table
External ID solves this: You tell Fineract externalId = "CRM-12345" when creating the client. From then on, you can call ALL Fineract APIs using your own ID instead of Fineract's.

API Pattern with External ID

Instead of:
javascript
QUBITS OF DPK
1GET /clients/42                     ← using Fineract's internal ID
You can use:
javascript
QUBITS OF DPK
1GET /clients/external-id/CRM-12345  ← using YOUR system's ID
All these endpoints exist for external ID:
javascript
QUBITS OF DPK
1GET    /clients/external-id/{externalId}                       ← get client
2PUT    /clients/external-id/{externalId}                       ← update client
3DELETE /clients/external-id/{externalId}                       ← delete client
4POST   /clients/external-id/{externalId}?command=close         ← close client
5GET    /clients/external-id/{externalId}/accounts              ← get all accounts
6GET    /clients/external-id/{externalId}/transferproposaldate  ← transfer date
7GET    /clients/external-id/{externalId}/obligeedetails        ← guarantor info

Auto-Generated External ID

Fineract can automatically generate a UUID as external ID if you enable the global configuration:
javascript
QUBITS OF DPK
1PUT /configurations/ENABLE_AUTO_GENERATED_EXTERNAL_ID
2Body: { "enabled": true }
Once enabled, every new client gets a UUID external ID automatically.

Client Identifiers (KYC Documents)

A client can have multiple identity documents:
javascript
QUBITS OF DPK
1POST /clients/1/identifiers
2Body: {
3  "documentTypeId": 1,       // Aadhaar, PAN, Passport etc.
4  "documentKey": "1234-5678-9012",
5  "description": "Aadhaar Card"
6}
Stored in m_client_identifier table.

Client Hierarchy — Office, Group, Client

javascript
QUBITS OF DPK
1Head Office (Office)
2    ├── Chennai Branch (Office)
3    │   ├── Self-Help Group A (Group)  ← group of clients
4    │   │   ├── Client: Deepak
5    │   │   └── Client: Priya
6    │   └── Individual Client: Rahul
7    └── Mumbai Branch (Office)
8        └── Client: Anjali
  • Office = Bank branch. Clients belong to an office.
  • Group = Cluster of clients (used in group lending). Optional.
  • Client = Individual person or entity.

Client Actions (State Transitions)

All these go through ClientWritePlatformServiceImpl via separate CommandHandlers.

GlobalConfigurationHelper — Feature Flags

The GlobalConfigurationHelper in tests manages Fineract-wide feature flags:
java
QUBITS OF DPK
1globalConfigurationHelper.manageConfigurations(
2    GlobalConfigurationConstants.ENABLE_AUTO_GENERATED_EXTERNAL_ID,
3    true  // enable auto external ID generation
4);
This maps to:
javascript
QUBITS OF DPK
1PUT /fineract-provider/api/v1/configurations/ENABLE_AUTO_GENERATED_EXTERNAL_ID
These flags are stored in c_configuration table and affect all tenants.

Mentor Cheat Sheet