Getting Started

This guide walks you through everything you need to do between receiving your Finecko credentials and having a configured, ready-to-use environment.

What You Receive at Onboarding

When your Finecko environment is provisioned, you receive:

API base URL - the HTTPS endpoint for your Fineract instance, e.g. https://your-instance.finecko.com
Tenant identifier - a short string that identifies your environment, e.g. default or a custom name agreed at signup
Initial admin credentials - username and password
Web UI access - a browser-based interface (Mifos X) for non-API access to your instance

Your environment is a fully provisioned Apache Fineract instance. All API calls target your base URL and must include the Fineract-Platform-TenantId header with your tenant identifier.

Step 1 - Verify Connectivity

Confirm your instance is reachable with a basic API call. This endpoint requires no special permissions:

bash

curl https://your-instance.finecko.com/fineract-provider/api/v1/authentication \
  -H "Fineract-Platform-TenantId: default" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "mifos", "password": "password"}'

A successful response returns a token and confirms the instance is running:

json

{
  "username": "mifos",
  "userId": 1,
  "base64EncodedAuthenticationKey": "bWlmb3M6cGFzc3dvcmQ=",
  "authenticated": true,
  "officeId": 1,
  "officeName": "Head Office",
  "roles": [...],
  "permissions": [...]
}

The base64EncodedAuthenticationKey is the Basic Auth token. Pass it as Authorization: Basic <token> on all subsequent requests, or use mifos:password encoded in Basic Auth directly while setting up.

Step 2 - Change the Admin Password

The default credentials (mifos / password) are well-known and must be changed before you grant anyone else access to the system or connect any external service.

bash

curl -X PUT \
  https://your-instance.finecko.com/fineract-provider/api/v1/users/1 \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "YourNewStrongPassword1!",
    "repeatPassword": "YourNewStrongPassword1!"
  }'

Use a strong password and store it in a password manager or secrets manager. All subsequent API calls use the new credentials.

Step 3 - Set Your Office Structure

Fineract organises clients and staff into an office hierarchy. The default deployment comes with a single "Head Office." Before creating any staff, clients, or loan products, set up the office structure that reflects your institution.

For a simple single-branch institution, rename the default Head Office to match your organisation:

bash

curl -X PUT \
  https://your-instance.finecko.com/fineract-provider/api/v1/offices/1 \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:YourNewStrongPassword1!' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme MFI Head Office",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en",
    "openingDate": "01 January 2020"
  }'

For multi-branch institutions, create child offices under the head office by passing a parentId. See the Office management feature page for the full hierarchy model.

Step 4 - Configure Accounting

Fineract uses double-entry accounting. Before you can create loan or savings products, you need a chart of accounts. A default chart is seeded at provisioning, but it needs to be reviewed and configured for your institution's specific GL structure before going live.

Check what account types exist in your instance:

bash

curl https://your-instance.finecko.com/fineract-provider/api/v1/glaccounts \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:YourNewStrongPassword1!' | base64)"

Consult the Accounting feature page for how the chart of accounts maps to loan and savings product configurations.

Step 5 - Create Staff

Staff are the loan officers, tellers, and branch managers that are assigned to offices and to client accounts. Create at least one staff member who will be associated with loan products and client records:

bash

curl -X POST \
  https://your-instance.finecko.com/fineract-provider/api/v1/staff \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:YourNewStrongPassword1!' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Jane",
    "lastname": "Nakamura",
    "officeId": 1,
    "isLoanOfficer": true,
    "joiningDate": "01 January 2024",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'

Step 6 - Create Your First Loan Product

A loan product is a template that defines the terms, repayment schedule, interest method, and accounting mapping for a category of loans. All loans are created from a product.

Key product settings to define:

Principal range (minimum, default, maximum)
Interest rate and calculation method (flat or declining balance)
Repayment frequency (weekly, monthly, etc.)
Repayment schedule type (equal instalments, equal principal, etc.)
Accounting mappings (which GL accounts to use for disbursements, repayments, income, etc.)

Creating a loan product is most easily done through the Mifos Web UI at first, since the API payload is large and the UI guides you through each section. The Loan management feature page describes each setting in detail.

Step 7 - Create Your First Client and Loan

Once a product exists, you can create a client and run a loan through its full lifecycle to verify everything is working end to end:

bash

# Create a client
curl -X POST \
  https://your-instance.finecko.com/fineract-provider/api/v1/clients \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:YourNewStrongPassword1!' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "officeId": 1,
    "firstname": "Amara",
    "lastname": "Diallo",
    "active": true,
    "activationDate": "01 January 2024",
    "dateFormat": "dd MMMM yyyy",
    "locale": "en"
  }'

From the client, submit a loan application, approve it, and disburse it. This exercise verifies that your accounting mappings are correct - after disbursement, check your GL accounts to confirm the expected journal entries were posted.

Step 8 - Create System Users

The default mifos admin account should not be used day-to-day. Create individual user accounts for each staff member who needs system access and assign them appropriate roles.

bash

curl -X POST \
  https://your-instance.finecko.com/fineract-provider/api/v1/users \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:YourNewStrongPassword1!' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jane.nakamura",
    "firstname": "Jane",
    "lastname": "Nakamura",
    "email": "[email protected]",
    "officeId": 1,
    "staffId": 1,
    "roles": [4],
    "sendPasswordToEmail": true,
    "password": "TempPassword1!",
    "repeatPassword": "TempPassword1!"
  }'

See User management for the available default roles and how to create custom roles.

Step 9 - Enable Business Events (Optional)

If you are integrating Fineract with external systems - sending notifications, updating a CRM, posting to accounting software - enable the business events pipeline. It is disabled by default.

Enable the master switch and specific event types via the configuration API:

bash

curl -X PUT \
  https://your-instance.finecko.com/fineract-provider/api/v1/externalevents/configuration \
  -H "Fineract-Platform-TenantId: default" \
  -H "Authorization: Basic $(echo -n 'mifos:YourNewStrongPassword1!' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "externalEventConfigurations": [
      { "type": "LoanApprovedBusinessEvent", "enabled": true },
      { "type": "LoanDisbursalBusinessEvent", "enabled": true },
      { "type": "LoanTransactionMakeRepaymentPostBusinessEvent", "enabled": true },
      { "type": "ClientCreateBusinessEvent", "enabled": true }
    ]
  }'

The broker connector (Kafka or ActiveMQ) must also be configured via environment variables on your instance. Contact Finecko support to enable the connector and provide your broker details. See the Business Events guide for the full setup.

Look for Loan COB in the response and confirm active: true and that nextRunTime is set. See the Close of Business page for what COB does and how to monitor it.

API Reference Basics

All Fineract API calls follow the same pattern:

Element	Value
Base path	`/fineract-provider/api/v1/`
Required header	`Fineract-Platform-TenantId: <your-tenant-id>`
Authentication	HTTP Basic Auth (`Authorization: Basic <base64(user:pass)>`)
Content type	`application/json`
Date format in payloads	Must specify `"dateFormat"` and `"locale"` alongside any date field

The full interactive API reference (Swagger UI) is available at:

https://your-instance.finecko.com/fineract-provider/api/v1/swagger-ui/index.html

See the REST API Overview for authentication patterns, pagination, and error handling details.

What to Set Up Next

Task	Guide
Configure loan and savings products in detail	Loan management, Savings & Deposits
Set up the full chart of accounts	Accounting
Create roles and restrict user access	User management
Connect to Kafka or ActiveMQ for events	Business Events
Add custom fields to clients, loans, accounts	Datatables
Configure additional tenants (if multi-tenant)	Multi-Tenancy
Understand COB and batch processing	Close of Business

Getting Started ​

What You Receive at Onboarding ​

Step 1 - Verify Connectivity ​

Step 2 - Change the Admin Password ​

Step 3 - Set Your Office Structure ​

Step 4 - Configure Accounting ​

Step 5 - Create Staff ​

Step 6 - Create Your First Loan Product ​

Step 7 - Create Your First Client and Loan ​

Step 8 - Create System Users ​

Step 9 - Enable Business Events (Optional) ​

API Reference Basics ​

What to Set Up Next ​

Getting Started

What You Receive at Onboarding

Step 1 - Verify Connectivity

Step 2 - Change the Admin Password

Step 3 - Set Your Office Structure

Step 4 - Configure Accounting

Step 5 - Create Staff

Step 6 - Create Your First Loan Product

Step 7 - Create Your First Client and Loan

Step 8 - Create System Users

Step 9 - Enable Business Events (Optional)

API Reference Basics

What to Set Up Next