Bulk Data Import

Apache Fineract supports bulk importing of core entities via Excel (.xlsx) templates. This is the standard approach for migrating an existing portfolio into a new Fineract instance, loading historical data, and onboarding large numbers of clients at once.

---

What Can Be Imported

Entity	Notes
Clients	Individual and joint accounts
Groups	Group membership and meeting configuration
Centers	Center-level group organisation
Loan accounts	Products must exist; clients must exist
Loan repayments	Loan accounts must exist and be disbursed
Savings accounts	Products must exist; clients must exist
Savings transactions	Deposits and withdrawals
Fixed deposit accounts	Products must exist
Recurring deposit accounts	Products must exist
Journal entries	Chart of accounts must be set up
Guarantors	Loan accounts must exist
Office	Batch office creation
Staff	Batch staff creation

---

Prerequisites: Import Order

The import system does not auto-resolve dependencies. Import in this order to avoid failures:

1. Offices (if importing multiple)
2. Staff / Employees
3. Clients
4. Groups and Centers (if applicable)
5. Loan Products (set up manually via API, not via import)
6. Savings Products (set up manually via API)
7. Loan accounts
8. Loan disbursements (if importing historical disbursed loans)
9. Loan repayments
10. Savings accounts
11. Savings transactions
12. Fixed/Recurring deposit accounts
13. Journal entries (for opening balances)

Attempting to import a loan account before the referenced client exists will fail for every row in that batch.

---

Downloading Import Templates

Fineract provides pre-formatted Excel templates for each entity type. Download the template for the entity you want to import:

GET /fineract-provider/api/v1/imports/downloadtemplate?entityType=clients&officeId=1&staffId=1
Authorization: Basic <base64>
Fineract-Platform-TenantId: default

The entityType parameter accepts:

Value	Entity
clients	Clients
groups	Groups
centers	Centers
loans	Loan accounts
loanRepayment	Loan repayments
savings	Savings accounts
savingsTransaction	Savings transactions
fixeddeposits	Fixed deposit accounts
recurringdeposits	Recurring deposit accounts
journalentries	Journal entries
offices	Offices
staff	Staff
guarantors	Guarantors

The template comes pre-populated with dropdown lists for valid values (office names, product names, staff names) drawn from your existing data, so you do not need to look up IDs manually.

---

Filling the Template

General rules

• Do not change column headers - the importer matches columns by name
• Do not add extra sheets - only fill the designated data sheet
• Date format - use the format shown in the template header row (typically dd MMMM yyyy or yyyy-MM-dd)
• IDs vs names - most columns accept human-readable names (office name, product name, staff name) rather than numeric IDs; use the dropdown lists in the template to avoid typos
• Leave optional columns blank - do not delete optional columns, just leave them empty

Client template key columns

Column	Required	Notes
Office Name	Yes	Must match an existing office exactly
Staff Name	No	Assigned loan officer
Legal Form	Yes	PERSON or ENTITY
First Name	Yes (PERSON)
Last Name	Yes (PERSON)
Full Name	Yes (ENTITY)
External Id	No	Your system's reference ID - useful for reconciliation
Activation Date	Yes	dd MMMM yyyy
Mobile No	No
Date of Birth	No

Loan account template key columns

Column	Required	Notes
Office Name	Yes
Client Name	Yes	Must match an existing client exactly
Product Name	Yes	Must match an existing loan product exactly
Loan Officer	No
Disbursement Date	Yes
Submitted Date	Yes	Usually same as or before disbursement date
Approved Date	Yes	Between submitted and disbursement dates
Principal	Yes
Number of Repayments	Yes
Repayment Frequency	Yes	Days, Weeks, Months, Years
Interest Rate (Per Period)	Yes
External Id	No	Your reference ID
Link Savings Account Id	No	For savings-linked loan products

---

Uploading the Completed Template

POST /fineract-provider/api/v1/imports
Authorization: Basic <base64>
Fineract-Platform-TenantId: default
Content-Type: multipart/form-data

Form fields:

Field	Value
entityType	Entity type string (e.g., clients)
file	The completed Excel file

Example with curl:

curl -k -u mifos:password \
  -H "Fineract-Platform-TenantId: default" \
  -X POST \
  -F "entityType=clients" \
  -F "file=@clients_import.xlsx" \
  https://<host>:8443/fineract-provider/api/v1/imports

The API returns immediately with a document ID. Processing happens asynchronously.

---

Checking Import Status

GET /fineract-provider/api/v1/imports?entityType=clients

Response includes the import job's status and any errors:

{
  "importId": 12,
  "entityType": "clients",
  "importTime": "2025-03-01T12:00:00Z",
  "endTime": "2025-03-01T12:00:45Z",
  "completed": true,
  "totalRecords": 250,
  "successCount": 247,
  "failureCount": 3,
  "importDocument": {
    "id": 45
  }
}

---

Downloading the Error Report

When some rows fail, download the error report to see exactly which rows failed and why:

GET /fineract-provider/api/v1/imports/{importId}/errorFile

The error file is the original Excel template with an additional Errors column added to failing rows. Each error message specifies the exact field and reason (e.g., "clientId not found: John Smith", "date format invalid in column DisbursementDate").

Fix the failing rows in the error file and re-upload it as a new import. Successfully imported rows do not need to be re-imported.

---

Importing Opening Balances via Journal Entries

For migration scenarios where you need to record the financial state as of a cutover date without replaying every historical transaction, import journal entries directly:

GET /fineract-provider/api/v1/imports/downloadtemplate?entityType=journalentries&officeId=1

The journal entry template lets you specify:

• Office
• Transaction date
• Currency
• Debit account (GL code)
• Credit account (GL code)
• Amount
• Comments

This is the recommended approach for recording opening balances when migrating from another system. See the Accounting Setup guide for the chart of accounts structure.

---

Tips for Large Migrations

• Split large files - import in batches of 500-1000 rows per file; very large files can time out
• Import clients first, verify before loans - check client counts match before proceeding to loan imports
• Use external IDs - populate externalId with your legacy system's record IDs; this makes reconciliation and debugging much easier
• Test with a small batch first - import 10-20 rows, verify the results, then proceed with the full dataset
• Keep the error files - they are your audit trail for the migration; archive them after the import is complete
• Match names exactly - office names, product names, and staff names are case-sensitive and must exactly match what exists in Fineract