Apache Fineract: Custom Data Fields with Datatables

Apache Fineract's datatable feature lets institutions extend any core entity - clients, loans, savings accounts, offices, or products - with custom fields specific to their business. No development work, database migrations, or application restarts are required. Custom data structures are created and managed through the platform and are immediately available for data entry.

What Problem Datatables Solve

Every financial institution collects data that the core system was not designed to capture. A microfinance lender might need household income and family composition for each client. An SME lender might track business registration documents and sector codes against each loan. A community bank might capture collateral assessments, visit notes, or survey responses.

Without datatables, these requirements either go unmet or drive custom development. With datatables, institutions configure exactly what they need - field by field - and Fineract handles storage, access control, and API exposure automatically.

What Can Be Extended

Custom data can be attached to any of the following core entities:

• Clients - additional KYC fields, household surveys, income verification, social data
• Groups - group profile information, meeting records, performance notes
• Loans - collateral details, purpose statements, sector classification, officer notes
• Savings accounts - account-level metadata, source of funds, intended use
• Loan products - product-level configuration or regulatory classification fields
• Savings products - product metadata for reporting or regulatory purposes
• Offices - branch-level data, regional classification, compliance attributes

One-to-One and One-to-Many Structures

Datatables support two relationship modes:

One-to-one - a single set of custom fields per entity. Suitable for fixed attributes like a client's household income range, a loan's sector code, or a savings account's source of funds declaration. Each client has exactly one row of supplemental data.

One-to-many - multiple entries per entity. Suitable for repeating structures: a client might have multiple family members on record, a loan might have multiple collateral items, or a group might have a history of meeting attendance records. Each entry is independently created, updated, and deleted.

Field Types Available

Institutions can define fields of the following types:

• Text fields - short or long text for names, descriptions, notes
• Numbers - integers for counts, years, quantities
• Decimals - monetary amounts, ratios, percentages
• Dates and date-times - for expiry dates, appointment dates, event timestamps
• True/false flags - boolean indicators for yes/no attributes
• Dropdown selections - linked to Fineract's code value lists for controlled vocabulary (gender, sector, document type, relationship type, etc.)

Controlled Vocabulary with Code Values

Dropdown fields reference Fineract's built-in code value system. This means custom dropdown fields automatically benefit from the same centralised list management used by the core system - update the code value list once and all dropdown fields using it reflect the change. This keeps data consistent and supports clean reporting.

Access Control

Every datatable respects Fineract's role-based permission system. When a datatable is created, the platform automatically generates read and write permissions for it. Administrators assign those permissions to roles as with any other feature. Loan officers see only the data within their office hierarchy. Branch managers see their branch. This means custom fields are as secure and scoped as core fields.

Business Use Cases

Extended KYC for clients

Regulators often require institutions to capture information beyond what a standard client profile holds - proof of income, source of funds, politically exposed person status, beneficial ownership. A one-to-one datatable on m_client captures this as structured, queryable data rather than free-text notes or external spreadsheets.

Household surveys and social performance

Microfinance institutions running social performance tracking need to record household composition, income sources, asset ownership, and poverty scoring per client. A set of datatables on m_client captures baseline and follow-up surveys independently, with one row per survey round.

Collateral management for loans

Secured lending requires tracking collateral items - property, vehicles, equipment. A one-to-many datatable on m_loan captures each collateral item as a separate entry, with fields for type, estimated value, registration number, and inspection date.

Loan officer visit notes

Field-based institutions track officer visits, repayment discussions, and client condition assessments. A one-to-many datatable on m_loan or m_client stores a timestamped log of each interaction.

Regulatory sector classification

Central bank reporting often requires loans to be classified by economic sector. A one-to-one datatable on m_loan with a sector dropdown field captures this at origination and makes it available for reporting queries.

Group meeting records

Group lending programs track attendance and repayment performance at each group meeting. A one-to-many datatable on m_group stores each meeting as a separate entry with date, attendance count, and amounts collected.

Integration with Reporting

Data stored in datatables is accessible through Fineract's reporting module. Stretchy reports and scheduled reports can query datatable fields alongside core entity data. This means custom fields feed directly into management reports, regulatory submissions, and portfolio analytics without additional data pipelines.

No Development Required

Datatables are fully self-service for administrators with the appropriate permissions. Creating, modifying, and removing custom data structures is an operational task. When a regulatory requirement changes, a new field is added in minutes - not in a development sprint.

For teams that need more - custom business logic, computed fields, or integrations that respond to datatable changes - Fineract's business events system fires events when datatable entries are created, updated, or deleted, enabling downstream processing via Kafka or ActiveMQ. See the Datatables API Reference for technical details.