Client identifiers in Apache Fineract

How Apache Fineract client identifiers fit your KYC process

A lender or microfinance team has to prove who each client is before the loan or savings account is activated. In Apache Fineract, the identity evidence sits in three places: the client record itself, code values that define the identifier types, and document attachments that hold the scanned originals. Fineract gives you the storage and the workflow hooks, but it does not decide which identifier types, number formats or duplicate rules your jurisdiction requires. Those rules come from your regulator, your KYC policy and your risk appetite, and they have to be translated into configuration and checks before the first client is onboarded.

You need this design at three points. The first is initial onboarding, when the identifier list and its mandatory status are fixed for every branch. The second is migration, when identifiers from a legacy system must be mapped, validated and deduplicated before they are loaded. The third is regulator or audit review, when you must show which identifier was checked, by whom and where the evidence is stored. The project documentation covers client data and KYC documents as a general capability, so the exact behavior of identifier fields, validation and duplicate handling must be confirmed against the Fineract version you run. The current stable release is 1.15.0, but confirm the behavior in your own instance rather than assuming it from the documentation summary. Start with the Apache Fineract platform documentation and test each identifier type in a non-production tenant.

Choosing how to model identifiers

Identifier types are held as code values, a list that administrators maintain in Fineract and attach to each client identifier record. The list gives every identifier type a stable, fixed key, so the same type can be selected, filtered and reported consistently across branches. The approach suits organizations with a short, agreed set of identifier types.

Who maintains the list: platform administrators with configuration permissions add or retire types, so changes should pass through your configuration change process and be recorded.
Validation: the list constrains the type only. Length, character set, check digits and issuing-country rules are not enforced by the list itself, so they need a validation layer in front of Fineract or custom code.
Reporting impact: the type is a discrete, filterable field, which makes counts by identifier type straightforward in reports and exports.
Migration effort: low when the set of types is small and agreed. Legacy labels from older systems must be mapped to the fixed list before loading, and unmapped values need a decision.
Limits: the identifier number itself is free text, so duplicate detection across clients is not provided by the code value list and must be designed separately.

Before committing, confirm in the Fineract version you plan to run how identifier code values are exposed through the API and whether the identifier endpoints enforce uniqueness of the number. The Fineract documentation is the starting point for that check.

Configuration options and when each fits

This table compares the five ways to record identity-related data on a Fineract client, from configurable identifier types to hard gates on activation. Read each row against the country and document mix you must capture, then confirm exact screens and API fields in your Fineract version before you commit to a design.

Option	What it stores	When it fits	Trade-off
Identifier type code values	A managed list of identifier types, such as national ID or passport, that staff select when recording an identifier against a client	One set of identifier types applies across the institution and the list changes rarely	Adding types is an administrative change, but the list is shared by every office and needs governance
Document types for attachments	Named categories for uploaded scans or files linked to a client record	KYC evidence must be stored as files and matched to a category for review	Attachments hold the evidence, not validated values, so checks depend on staff or extra rules
Custom data table fields for country-specific IDs	Extra columns on a client-linked data table, such as tax numbers or regional registration IDs	A country or product needs fields that a generic identifier type cannot describe	Each data table is designed and maintained separately, and reporting across countries needs consistent field names
Mandatory-field rules through data tables	A rule that blocks specified client actions, such as activation, until the linked data table has values	Policy requires an identifier before a client can become active or take a loan	Rules apply to the actions you scope, so each rule must be tested to confirm it blocks the right step
External reference fields	A reference to an identifier held in another system, such as a core customer or KYC vendor record	Identity is verified or owned outside Fineract and you need a link back	The reference is only as current as the sync, and the source system becomes part of your control scope

How to configure identifiers and duplicate checks

This sequence turns an agreed list of identity document types into Fineract configuration, then proves with test clients that duplicates are caught and missing identifiers are handled before any real customer data is loaded. Each step ends with a check you can repeat after every change.

Agree the identifier catalogue with compliance
Compliance, the business owner and the implementation lead list every identifier the institution must hold for each client type and jurisdiction, such as national ID numbers, passports, tax numbers and registration numbers. For each entry they record whether it is mandatory, optional or conditional, its format rules, and who may override it. The output is a signed-off catalogue that becomes the specification for every later step. Confirm the regulatory basis for each identifier with your own compliance function, since DeployOpen does not advise on which identifiers a given regulator requires.
Create identifier code values
Using an administrator account on a non-production tenant, add the agreed identifier types as code values in Fineract's administration area so that each client identifier references a controlled list rather than free text. Keep the code names stable, because they will appear in API payloads, reports and migration files. Export the code values from the test tenant and compare them against the catalogue line by line. The step is complete when every catalogue entry exists exactly once and no stray test values remain.
Attach document types to identifiers
Define the document types that hold scanned evidence for each identifier, such as a passport copy or a national ID card image, and associate them with the matching identifier types. Decide which document types are required before activation and which are kept for reference only, and record that decision in the catalogue. Upload a sample file to a test client and confirm it appears under the correct document type with the expected identifier linked. Pending decisions on retention and file access belong to your security and records owners, not to the configuration itself.
Add data tables for fields outside the identifier model
Where the catalogue needs values that the standard identifier structure does not hold, such as issuing country, expiry date or issuing authority, create an entity data table linked to clients. Set the column types, mandatory flags and any allowed values, then check in the client view that the fields render and save correctly. Use data tables only for supplementary attributes, so the identifier value itself stays in the identifier record. Confirm the data table names and column definitions match the design document before migration mapping starts.
Define the duplicate matching rule
Choose how the institution decides that two clients are the same person: exact matching on the normalized identifier value, normalized matching that strips spaces, hyphens and leading zeros and applies case folding, or fuzzy matching on name and date of birth combined with identifiers. Document the rule, the fields it compares, how it treats the same identifier across different identifier types, and who reviews a possible match. Fineract's identifier model does not settle this choice for you, so any check beyond what the platform provides is usually built as a custom validation or an external screening step. Confirm with your engineers which layer will enforce the rule, because that decides how it is tested and maintained.
Test client creation with duplicates and missing identifiers
Create a test set of clients that includes a repeated national ID, the same ID written with different spacing or formatting, a missing mandatory identifier and a valid new client, then submit each through the client creation API or screen. Record the response for every case, including whether the duplicate was blocked, flagged for review or accepted, and whether the error message names the identifier. For example, creating a second client with a national ID already used by an active client should produce the outcome your matching rule defines, and the test passes only if the actual behavior matches it. Repeat the set after any change to the rule or the code values.
Load and reconcile a test migration file
Prepare a small migration file with clients carrying identifiers, including a deliberate duplicate and a row with a malformed identifier, and load it into the test tenant using the import method your migration plan selects. Compare the imported identifier records, document links and data table values with the source file, and confirm that rejected rows are reported rather than silently dropped. The step closes when the counts of loaded, rejected and flagged rows match the expected results you wrote down before the load. Only after this reconciliation should the full migration rules be frozen.

Why duplicate checks sit outside the core and how to build them

Duplicate detection around identifiers is usually an implementation layer, not a stock Fineract feature. The client record can hold identifiers as typed values, but the decision about whether a new national ID, passport number or other document number has already been seen belongs to your onboarding design. Teams typically choose one of three places to enforce it: a pre-creation check called by the onboarding front end or middleware before the client create call is made, a custom validator added through the project's extension mechanisms, or a periodic report that flags likely duplicates for a back-office review. Each has different failure modes. A pre-creation check is fast but can be bypassed by any client that calls the REST API directly, a validator sits closer to the data but must follow Fineract's extension guidance, and a report catches what the other two miss but acts after the record exists. Confirm with your architects which combination your channels and API consumers will actually respect before you write any code.

Normalization decides how many false matches and misses you get, so define it before the first comparison runs. Identifiers arrive with spaces, hyphens, leading zeros that some sources drop and letter case that varies by keying channel. Names used in secondary checks raise transliteration questions, since the same person may be recorded in different scripts or spellings across branches. Write down the canonical form for each identifier type (for example, stripping separators and fixing case) and test it against a sample of real migrated records, keeping in mind that the sample must be handled under your data protection rules. Legitimate duplicates also need explicit rules. Family members may share a household document or a joint record, and some identifier types are reissued after loss. Model these as allowed relationships with a reason code, not as exceptions that staff can switch off silently. Ask your compliance lead which identifiers must never be shared and which may be.

Every hit needs a documented override and approval path, and the override must leave evidence. A check that blocks onboarding with no route forward will push staff to work around it through a second record or an informal data entry, which is the outcome the control exists to prevent. Define who may review a match, what they must confirm, who approves an override, and how the decision is recorded, including a reason code and a reference to the attached KYC document. Keep the approval step in the workflow your onboarding design already uses, and confirm how it interacts with pending client statuses. Build the custom logic as an extension that sits beside the core, following the extension and custom development guidance in the project documentation, so that upgrades to later 1.x releases do not require merging changes into a fork. Test the override path as carefully as the block itself, because it is where audit questions will land.

Protecting identity data in Fineract

Identifier fields and scanned documents are some of the most sensitive records a Fineract deployment holds. The controls below work together: limit what is captured, restrict who sees it, protect it at rest and in transit, and keep a record of changes. Each one is a decision you make in your own infrastructure and should be checked before go-live.

Minimize identifier data captured

Capture only the identifier numbers your onboarding policy and local rules require, and avoid copying full document numbers into free-text notes, comments or loan purpose fields. For each identifier type configured as a code value, decide whether the number is mandatory, optional or not collected at all. Review who can export client records, because a report that includes the identifier column multiplies exposure. Confirm the field list with your compliance owner before migration loads historical data.

Restrict document access by role

Scanned national IDs and passports are stored as document attachments on the client record, so anyone who can read the client can often open the file. Map which roles may view, upload, replace or delete attachments, and test those roles against a sample client in a non-production tenant. Keep branch staff who only collect repayments away from identity documents they do not need. Confirm the role-to-permission mapping in your deployment, since permission names change between releases.

Encrypt stored documents and backups

Fineract's database holds the identifier values, and the document store holds the scanned images, so both need encryption at rest. Decide where attachments are stored, whether the storage layer encrypts them, and who holds the keys. Backups of the PostgreSQL database and the document store carry the same data and need the same protection, along with a tested restore procedure. Ask your platform team to confirm how keys are rotated and who can restore a backup into a non-production environment.

Audit identifier edits

Changes to identifier numbers and attachments should leave a trail showing who changed what and when. Confirm which audit records Fineract keeps for client data changes in your release, and whether they cover identifier edits and attachment deletion. Where the built-in trail is not enough, plan an export of audit data to your central logging system. Review the trail on a fixed schedule, not only after an incident.

Serve the API over HTTPS only

Identifier numbers and document uploads travel through the REST API, so TLS must cover every client and integration path. The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Terminate TLS at a gateway or the application, set up certificate renewal, and block plain HTTP at the edge. Test uploads from the front end and from each integration, because one unencrypted caller undermines the rest.

Remove the default development login

The Fineract README shows a default development login, mifos, with a default password that must be changed for any real deployment. Before any environment holds real client data, replace the account, set a strong password or move authentication to OAuth2, and confirm the default is gone from every tenant. Check seeded data and integration accounts too, since a default credential left in one tenant is a direct route to all identifier records.

Questions teams ask about Fineract client identifiers

How much effort does setting up client identifiers in Fineract take?

Effort depends less on the configuration itself than on the rules your organization must support. Creating identifier types as code values is a small configuration task, but the surrounding work adds up: agreeing which document types each market accepts, deciding which fields are mandatory, defining formats for each national ID scheme, and designing how attachments are stored and reviewed. Expect the most time to go into validation rules and duplicate handling, and into testing edge cases such as expired passports, re-issued IDs and clients who hold several documents. Ask any partner for a written scope that lists each identifier type, each market, and each check, because those lists are what move a quote up or down.

Can our own team configure client identifiers without outside help?

A team with working Fineract administration experience can usually create identifier types, code values and client data tables without outside help, provided it has a test environment and clear requirements. Outside help becomes more valuable when the design touches several systems, when duplicate checks need custom API logic, or when identifiers must be verified against external registries. Before deciding, confirm who on your team will own the code values, who approves changes to mandatory fields, and who tests the result after each Fineract upgrade. A partner can plan and build the design, then hand over documentation and run-books so your staff can maintain it.

What does a duplicate-check build depend on?

A duplicate check depends on the identifier data being consistent, normalized and available at the moment a client is created or edited. Fineract stores identifiers against clients, but the rules that decide two records are the same person usually live in your own code or workflow. You need a defined matching rule (for example, exact match on a national ID number after formatting), a decision on whether matches block creation or only raise a review, and a way to search existing records quickly as the client base grows. Each of these choices changes the build, so document them before development starts and test them with deliberately messy data.

How are existing client identifiers migrated into Fineract?

Migration starts from what your source system holds, not from what Fineract expects. Map each legacy identifier type to a code value, normalize number formats, and decide what happens to records with missing or invalid identifiers. Attachments such as scanned passports need a separate plan for storage location, naming and access rights. Confirm with the project's migration documentation which import paths and templates your Fineract version supports, and test a full load in a non-production environment before cutover. Plan reconciliation reports that compare record counts and identifier values between the source and Fineract, because a mismatch found after go-live is far more expensive to fix.

What do compliance and operations need to provide for identifier handling?

Compliance owners need to state which identifiers must be collected for each product and market, how long documents are retained, who may view them, and how changes are approved and logged. Operations teams need to know who maintains code values, how duplicate alerts are worked, and how backups cover attachment storage as well as the database. Fineract can record data and attachments, but it does not decide your regulatory obligations, and independent auditors assess whether your controls work. Ask any implementation partner to map these responsibilities in writing, so compliance, operations and engineering each know what they own.

Which security controls should protect identifier data?

Identifier data is personal data, so access should follow the same role model as the rest of the client record. Restrict who can view or export identifiers and attachments, enforce HTTPS for every API call that carries them, and make sure logs do not write full identifier numbers. Confirm how your deployment stores attachments and whether they are encrypted at rest. Plan periodic access reviews for staff roles, and test that a user from one office cannot read identifiers from another office unless policy allows it.

Does licensing or vendor choice change how identifiers are built?

Apache Fineract is licensed under the Apache License 2.0, so your organization can use, modify and deploy it without a license fee for the software itself. Costs come from the work around it: design, configuration, testing, hosting and support. Whether you use an outside partner for that work is an ownership decision, not a licensing one. Ask each vendor to state in writing what it will build, what it will hand over, and how it will support changes after go-live.

Limits to confirm in your environment

Fineract's identifier handling depends on the release you deploy, the rules in your market and the storage you run. The cards below list the points to confirm with the project documentation, your regulator and your own infrastructure team before the design is final, because each one changes what the implementation must build.

Supported identifier fields and validations

Confirm which identifier fields, types and validation rules your Fineract version provides out of the box, and which must be added as configured code values or custom code. Check the exact release you plan to run against the current stable line, since field behavior can differ between releases. Test a national ID format, a passport with an expiry date and a foreign-issued document in a non-production tenant before you write the design down.

Duplicate detection timing

Confirm how duplicate identifiers are detected, whether the check runs at client creation, at activation or only in a report, and whether it compares identifier values alone or values combined with name and date of birth. A check that runs only after activation lets a duplicate reach a live loan. Record the result of a deliberate duplicate test as evidence.

Document storage location and retention

Confirm where scanned identity documents are stored, which storage backend holds the files, who can read them and how long copies are kept after a client closes. Attachment storage and the database backup set are separate paths, so both need a retention rule and a deletion procedure. Ask your data protection lead to sign off on both before go-live.

Regulator identifier rules per market

Confirm with each regulator which identifiers must be collected, how they must be verified and whether a particular format or issuing authority is required. Rules for tax numbers, national IDs and refugee or residence documents often differ by country and by product. Map each rule to a Fineract code value, a data table field or a documented manual step, and keep the mapping under change control.

No certification implied

Configuring identifier fields and attaching documents prepares evidence for a compliance review. It does not make the deployment compliant or certified. DeployOpen prepares systems, controls and evidence, and independent auditors and certification bodies issue any report. Ask your assessor which artifacts they need before you collect them.

Running identifier data after go-live

Identifier types are configuration, so changes to them need the same control as any other change to the platform. Identifier types are held as code values, and adding a new type such as a tax number or a regional registration ID is a configuration change that alters what front-end forms accept and what the duplicate checks compare. Record each addition with its owner, the reason, the validation rule agreed with compliance, and the date it went live. Confirm in your own test environment how a new code value appears in existing client records and reports before it reaches production, because older clients will not gain the new type automatically. Keep the code value list under the same change approval you use for product configuration.

Duplicate-check overrides and rejected creations are the signals that show whether the identifier rules still fit real onboarding. Review the exceptions your front end or integration layer records on a fixed schedule, and check which overrides were approved, by whom, and whether the supporting document is attached to the client. Ask your integration team to log every rejected creation with its reason so that a rise in rejections, which can point to a bad validation rule or a changed document format, is visible before field staff complain. Treat an unexplained pattern of overrides as a potential control failure rather than a training issue.

Backups must cover document attachments as well as the database, because an identifier is only as useful as the scanned passport or national ID that supports it. Confirm with your storage and database teams that the attachment store and the PostgreSQL database are backed up at the same point in time, and test a restore that checks one client's identifier, its code value and its attached file together. Schedule regression tests for identifier creation, duplicate checks and attachment retrieval before each Fineract release upgrade. The project publishes its releases quarterly, which is a sound reason to build that test into a recurring calendar, but the test itself should be driven by your own identifier configuration, which the upgrade notes will not cover for you.

How DeployOpen works on this

DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own infrastructure. For client identifiers in Apache Fineract, we start with a written scope that fixes which identifier types, documents and duplicate rules are in play, then build and test them in your environment before handing over the configuration and runbooks.

How we scope

We list the identifier types your jurisdictions require, such as national IDs, passports and tax numbers, and confirm each one's format rules.
We agree which identifiers are mandatory, optional or restricted to specific client types before any configuration starts.
We map where identifier checks run, whether in the onboarding workflow, entity-datatable checks or external KYC tooling, and record that decision in writing.

How we build

We configure identifier types as code values in a non-production Fineract tenant and review the list with your compliance and operations leads.
We attach document upload rules and duplicate checks, then test them with synthetic records that cover valid, invalid and conflicting cases.
We keep configuration under version control so each change to identifier types or checks can be reviewed, tested and reproduced in later environments.

How we hand over

We deliver a written record of identifier types, validation rules, duplicate logic and document attachment settings, with the test results behind each one.
We run a handover session with onboarding, branch and compliance staff so they can explain and apply the rules without DeployOpen present.
We document the steps to add a new identifier type or change a duplicate rule, including who approves the change and how it is tested.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, so identifier rules can be reviewed when regulations or Fineract releases change.
Retainer support can cover re-running duplicate and validation tests after each Fineract upgrade, before changes reach production.
Any support work for identifier data stays inside your infrastructure, under the access and data handling terms agreed in the written scope.