Poverty scorecards and client surveys in Apache Fineract

Why poverty scorecards belong in your Apache Fineract client record

A microfinance institution often has to collect poverty scorecard answers or other survey responses from each client and then report outreach figures to funders. The reason to keep those answers in Apache Fineract, rather than in a spreadsheet beside it, is that the client record is where the institution already holds identity, loan and savings history, and branch assignment. Keeping survey answers on the same client means outreach reports can be produced from the system of record instead of rebuilt by hand each quarter. Fineract's documentation describes client data and KYC documents, along with configurable data that can be attached to clients. It is the basis for planning survey capture, but the documentation does not, on the material supplied here, establish a dedicated survey or poverty scorecard feature. Confirm against the Fineract version you run, and against the exact release notes, whether survey definitions, scoring logic and response storage exist natively or must be built as custom data.

Teams usually need this capability for three reasons: funder reporting that asks for the distribution of clients by poverty likelihood, targeting analysis that checks whether lending reaches the intended segments, and consent-based collection where the client agrees to answer and to how the answers are used. Each reason changes the design. Funder reports need stable definitions and an audit trail of when a score was taken. Targeting analysis needs responses linked to loans and offices. Consent needs a recorded decision that can be shown later, so a survey answer should never be stored without a way to tie it to that decision. Decide early which of these you must satisfy, because it determines which fields are mandatory and which reports you build.

Fineract is headless. It exposes REST APIs and does not provide a user interface of its own, so the survey questionnaire, the enumerator experience and any scoring step must come from the front end and integration layer your team builds or selects. The Mifos X web application is one front end the project references. Before choosing, confirm how that front end collects and validates survey responses, how it writes them through the API, and how a failed partial save is handled in the field, where connectivity is often poor. These decisions sit with the platform team as much as with the programme team.

Survey configuration options and when each fits

This table compares four ways to capture PPI scorecard and survey answers around Apache Fineract, showing what each stores, who enters the data, how it reports and when it fits. Read each row against your own staffing and reporting needs, and confirm every built-in capability in the Fineract release you plan to run before you commit to a design.

Option	What it stores and who enters it	How it reports	When it fits
Built-in survey features	Survey definitions and responses held in Fineract if the chosen release provides them. Field staff or officers enter answers through the Mifos X front end or another client of the REST API.	Depends on the release. Confirm whether responses are exposed through reports, the API or only through the database.	Suits teams that want a single system of record and whose target release has the feature. Confirm scope, versioning and export before relying on it.
Data tables attached to clients	Scorecard questions and scores stored as entity-datatable fields on the client record. Officers enter answers when they edit the client, with values validated by the table definition.	Available through Fineract reporting and the data table API. Outreach counts need a query or report built for the purpose.	Suits a modest number of fixed questions that must sit on the client and be checked at onboarding or renewal. Each new survey version usually means a new data table, so plan the change control.
Separate survey service via REST API	Responses held in a service you build and operate, which writes summary or client-level results back to Fineract through the API. Enumerators or a mobile app enter answers in the survey service.	Reporting is handled by the survey service, with optional write-back of scores to Fineract for loan decisions and funder reports.	Suits programs with multiple survey waves, offline collection or several question sets. It adds a system to secure, back up and support, and the integration must be tested for failed writes.
Spreadsheet or external tool with periodic import	Answers collected in a spreadsheet, form tool or survey platform and loaded into Fineract on a schedule. Data entry sits outside Fineract, and import files need a named owner.	Reporting is done in the external tool. Fineract holds only what the import writes, so reconcile counts after each load.	Suits short pilots or small portfolios. Manual steps increase error risk, and funder audit trails depend on keeping the source files and import logs.

How to configure a PPI survey in Fineract, step by step

This sequence takes a team from licensing and version checks through to a tested, access-controlled survey configuration in Fineract, with a check at each step so the team can show that stored scorecard values match the source sheet before any live client is surveyed.

Confirm the scorecard licence and questionnaire version
Before any build work, the programme lead confirms with the scorecard publisher which questionnaire version, country table and scoring sheet the organization is licensed to use, and whether the licence allows storing responses in a self-hosted system. Ask the publisher in writing for the current scoring tables and the version identifier that must appear on every record. The step is done when you hold a dated written confirmation and a copy of the scoring sheet that your testers will check against, and when the legal or compliance owner has signed off the storage approach.
Confirm the Fineract release and survey capability
The platform team confirms which Fineract 1.x release is running in the target environment and checks the official documentation for that release to see how surveys, questionnaires and their responses are modelled, including whether a native survey feature exists or whether the team must use entity data tables. Record the release identifier and the capability found, and note any gap, such as missing scoring logic, that the build must cover. The step is done when the release and the chosen storage mechanism are written into the design record.
Define the response model and code values
The product owner and data lead define each questionnaire question, its answer options and the score each option carries, then map every answer to a code value or typed field. Decide the fields that store the questionnaire version, the country table, the total score, the estimated poverty likelihood and the date of the interview. Use a mapping table that links each question to its Fineract field name. The step is done when the mapping table has been reviewed against the publisher's scoring sheet and every question has exactly one target field.
Configure storage on a non-production tenant
The platform engineer creates the code values and data table or survey structure on a non-production tenant, identified by the Fineract-Platform-TenantId header, and never on the production tenant. Configuration is applied through the API so that each change can be repeated in other environments. Keep the configuration as versioned scripts in the team's repository. The step is done when the non-production tenant lists the expected fields and code values, and a second environment built from the same scripts produces an identical structure.
Create test clients with known profiles
The QA lead creates a set of test clients on the non-production tenant, covering the household profiles on the scoring sheet, including edge cases at score boundaries and answers that should be rejected. Use clearly fictitious names and identifiers so no real personal data enters a test system. Record each test client's expected total score and likelihood from the scoring sheet before any response is entered. The step is done when the expected results for every test client are written down and reviewed by someone who did not build the mapping.
Capture test responses through the API
The integration engineer submits the test responses for each test client through the Fineract REST API, using the same request pattern the live process will use, and records the response identifiers returned. Include at least one invalid submission to confirm the system rejects missing or out-of-range answers. Keep the request and response logs for the test run. The step is done when every test client has a stored response and every invalid submission has been refused with a recorded error.
Verify stored values against the source sheet
The QA lead reads each stored response back through the API and compares every answer, the version, the total score and the likelihood with the expected results recorded earlier. Any mismatch is logged with the question, the expected value and the stored value, then traced back to the mapping table or the scoring logic. The step is done when every test client matches the source sheet with no unexplained differences, and a signed test report is filed with the design record.
Test access rights before rollout
The security engineer creates test users for each role, such as field officer, branch manager, auditor and an account with no survey permission, and checks what each can read, write, edit and export. Confirm that only authorised roles can create or change responses and that edits leave an audit trail. Check that the exported outreach reporting does not expose identifiers beyond what the funder requires. The step is done when each role's permissions match the written access model, every unauthorised action is refused, and the results are approved by the data owner before any live client is surveyed.

Outreach metrics funders ask for, and who uses each report

Funders and investors ask about reach and depth of outreach: how many clients were surveyed, which poverty levels they fall into, and how that profile changes over time or across products and regions. Answering this requires that each survey response is linked to a specific client, a specific scorecard version and a recorded collection date, so that the figures can be filtered and reproduced later. Fineract stores the responses against the client, so the report is usually produced from the database or an analytics layer built on it, not from a screen inside Fineract.

Indicator definitions: Obtain the exact indicator definitions, cut-offs and reporting periods from each funder in writing. Do not reuse another funder's wording for the same figure.
Scorecard version: Record which scorecard and version was administered, because a funder may accept only certain versions for a given reporting period.
Collection date: Store the date each survey was completed so that reporting windows are applied consistently.
Consent status: Report only on clients whose consent to be surveyed and to share data with the funder is recorded, and confirm the funder's rules on aggregated versus individual-level data.
Reproducibility: Keep the query and the extract used for each submission so that a figure can be explained when the funder asks.

Before the first submission, confirm with each funder the required format, the reporting calendar and whether they accept self-reported figures or require an independent review.

Protecting poverty and personal data in survey responses

Poverty scorecard answers and other survey responses describe household income, dependants and hardship, which makes them sensitive personal data. The risks below sit across transport, access, retention and export, so each card pairs a risk with the Fineract control the documentation describes and the check still to be made against the data protection rules that apply to you.

Household and income data in transit

Scorecard responses travel from field devices and browsers to the Fineract REST API, so an unencrypted connection exposes income and household answers to anyone on the path. The Fineract documentation strongly encourages HTTPS only and documents SSL settings through environment variables such as FINERACT_SERVER_SSL_ENABLED. Confirm that TLS terminates on every path that carries survey traffic, including any gateway, load balancer and reporting connection, and that plain HTTP is refused rather than redirected.

Default development credentials

The Fineract README shows a default development login of mifos with a matching password. Any environment that still accepts it, including a staging copy loaded with real client surveys, hands full API access to whoever finds it. Replace the default credentials before any data is loaded, record who holds the replacement, and confirm that no sample or demo account carries survey permissions in production.

Weak authentication on field access

Field officers often enter scorecard answers on shared or personal phones and tablets in areas with poor connectivity. Basic authentication sends credentials with every request, so it depends entirely on HTTPS being enforced. Where OAuth2 is used, decide how sessions expire on lost devices and who can revoke them. Confirm which mechanism your deployment uses for field users and whether it meets the multi-factor expectations your regulator applies to remote access.

Over-broad API permissions

A user who can read client records can often also read every survey response linked to them, unless roles are scoped. Survey data should be readable only by the staff who collect or review it, and not by every account that can view a client profile. Review the roles that include survey and data table access, remove permissions from reporting or integration accounts that only need aggregate counts, and test each role with a non-privileged user before go-live.

Responses kept after the project ends

Funder projects end, but the responses they generated can remain in the database, backups and exports long after the reporting period closes. Define a retention period for each survey in writing, agree who deletes or anonymizes records at the end, and check whether backups must follow the same rule. The retention limit that applies to you comes from your funder agreement and data protection law, so confirm it with your legal or compliance team before configuring the survey.

Raw file exports leaving the system

Spreadsheet exports of individual responses are the most common route by which household data leaves a controlled system. Limit exports to aggregated outreach figures for funder reports, restrict individual-level exports to named roles, and decide where exported files are stored and deleted. Log who exports what and when, and confirm that any export path your team uses is covered by the same access and retention rules as the database itself.

Which survey features to confirm in your Fineract version

The research behind this page does not confirm which survey features, scorecard scoring logic or report templates Apache Fineract provides in any given release, so treat every survey capability as unverified until your team has checked it. Start with the release notes and documentation for the exact version you run, and read them against the survey, questionnaire and client data features you need: how a survey is defined, which fields a scorecard can hold, whether scores are calculated by the platform or entered by staff, and what reports exist for outreach counts. Use the Apache Fineract platform documentation as the starting point, but record the version number beside every finding, because the documentation for one release does not describe another.

Next, run a proof of concept on a test tenant that mirrors your production configuration. Tenants are separated by the Fineract-Platform-TenantId header, so a disposable tenant lets you load a sample scorecard, collect test responses for a few clients, and see what the API returns and what the reports show. Confirm that responses are stored against the right client, that edits and reversals are recorded, and that outreach figures match a manual count from the test data. If a feature is missing or only partly supported, the proof of concept shows whether you need configuration, custom development or a process change, and that decision belongs in the scope before any build begins.

Third, obtain written confirmation from the publisher of any scorecard you plan to use. Ask who owns the scoring method and its parameters, whether you may reproduce the questions and scoring tables inside a self-hosted system, which uses are permitted, and whether any reporting or data-sharing terms apply. Keep that confirmation with the implementation records. Because the Fineract project ships quarterly releases under its release policy, repeat all three checks before each upgrade, since a feature confirmed in one release may change in the next.

Limits to confirm in your environment before committing

A poverty scorecard and its surrounding survey depend on rights, method and tooling that sit partly outside Fineract. The cards below list the points to settle with the scorecard publisher, your Fineract team and your field operations before you build.

Licensing for your country

Confirm in writing that the scorecard publisher allows your organization to use the instrument, in your country and for your lending volume. Ask whether the scoring tables are licensed separately from the questionnaire, whether there are fees per assessment or per year, and whether the license covers a self-hosted deployment. Fineract's own Apache-2.0 license does not extend to third-party scorecard content.

Fineract version and survey pattern

Confirm that the Fineract release you plan to run supports the survey pattern you choose, whether that is data tables, custom code or an external survey service. Check the release notes for the version you target, and plan for the quarterly release cadence so the pattern survives upgrades. Ask the internal team who will own the custom parts after go-live.

Versioning when questionnaires change

Publishers revise questions, scoring tables and country sets over time. Decide how each stored response records the questionnaire version, scoring table version and date it was completed, so older scores can still be read and audited. Ask the publisher how revisions are announced and how long a previous version remains valid for new assessments.

Score validation against the publisher method

A computed score must match the publisher's method exactly before funders will accept it. Ask the publisher for worked test cases with expected scores, and build tests that feed those cases through your calculation. Ask whether the publisher offers a validation or certification service, and document who signed off the implementation and when.

Offline capture and sync

Field officers often complete surveys without connectivity. Confirm which tool captures responses offline, how it authenticates, and how records sync to Fineract without duplicates or lost answers. Ask the internal team how partial submissions, device loss and conflicting edits are handled, and who reviews sync failures on meeting days.

Consistency across tenants

Fineract is multi-tenant, so each tenant may hold its own copy of questions, scoring rules and reports. Ask the internal team who owns the master survey definition, how changes are pushed to each tenant, and how drift is detected. Estimate the recurring effort of keeping tenants aligned before you agree the scope in writing.

Questions to answer before hiring help with surveys in Fineract

What drives the cost and effort of a survey build in Fineract?

The main drivers are how many survey types you need, how complex the scoring logic is, how many data points each survey stores, and how many systems the answers must reach. A single PPI-style scorecard stored against clients is a bounded task. Multiple surveys with conditional questions, scoring rules that differ by country or product, and reporting for several funders add configuration, testing and review effort. Ask any partner to price the written scope in parts: survey design, configuration, integration or reporting, and testing. Request a list of assumptions, including which environments are covered and who signs off each survey before go-live. DeployOpen does not publish prices; a quote follows from the written scope.

How long does survey configuration and testing usually take in Fineract?

Duration depends on the same factors that drive cost, plus how fast your funder and scorecard owner confirm definitions. Expect the schedule to stretch if indicator definitions change after build starts, if scoring tables must be validated against a licensed source, or if survey responses need to flow into external reporting. Testing time grows with the number of survey versions and the number of client segments that take different paths. Ask for a schedule with named review gates: definitions approved, configuration built, test data loaded, outreach report reconciled against a known sample, and sign-off. A timeline without these gates is hard to check.

What does our team need to provide before a survey project starts?

Three inputs usually decide whether the work starts smoothly. First, confirm you hold the right to use the scorecard you plan to collect, including any licence terms from the scorecard owner, and do not assume a public question list is cleared for commercial use. Second, provide sample data, anonymized or synthetic, that reflects your client base, so testing reflects real answer patterns. Third, get written indicator definitions from each funder: the exact fields, reporting periods, categories and how outreach is counted. Missing any of these typically adds rework. Put them in the quote as client dependencies with owners and due dates.

Can our own team build surveys in Fineract without outside help?

Yes, a capable team can configure surveys in-house if it has Fineract administration skills, access to a non-production environment, and someone who owns the scoring logic and funder definitions. Outside help usually adds value on the parts that are easy to get wrong: mapping survey outputs to reporting, testing edge cases, designing a repeatable change process, and documenting controls for auditors. Decide which parts to keep internal based on who will maintain the configuration after go-live. If your team will own the work, ask a partner for a knowledge transfer and runbook as a deliverable in the quote.

What changes after a Fineract upgrade to survey configuration?

Survey configuration is custom data on top of the platform, so each Fineract upgrade needs a regression check rather than automatic trust. Review the release notes for the version you are moving to, confirm the APIs your survey integrations call still behave the same, and re-run the test cases that cover answer storage and reporting. Fineract publishes quarterly releases, so plan an upgrade cadence that includes survey testing each time. Ask whether the quote covers upgrade regression testing, and whether it is in scope for a fixed price or billed separately.

Which costs are one-time and which recur for surveys?

One-time costs usually include scope and design, initial configuration, test data preparation, integration or reporting build, and staff training. Recurring costs include hosting and maintenance of the environment, review of scorecard or indicator changes when funders revise definitions, periodic regression testing after upgrades, and support for new outreach reports. Ask for the quote to split these into separate lines so you can see what continues after go-live. Also ask who holds the scorecard licence and whether any licence fees recur, since these are set by the scorecard owner, not by the implementation partner.

How should we check that survey answers and outreach reports are accurate?

Accuracy checks should be part of the acceptance plan, not an afterthought. Load a known set of test responses with expected scores and expected outreach counts, then compare what Fineract stores and reports against those expected results. Repeat the check for each survey version and each funder report. Keep the test cases and results as evidence. Ask for these test artefacts as a deliverable, and confirm who approves the expected results. Auditors and funders may ask how you know the figures are right, so this record matters as much as the configuration itself.

How DeployOpen works on this

DeployOpen plans, implements, customizes and documents self-hosted Apache Fineract inside your own infrastructure, including survey configuration and reporting for poverty scorecards and client surveys. Engagements start from a written scope that sets out the survey instruments, data fields and reports before any build work begins.

How we scope

Inventory which poverty scorecards, country-specific instruments and client surveys your funders require, with their versions and scoring rules.
Define which survey answers are stored, who can enter them, and where the records sit in your Fineract tenant.
Agree in writing the outreach metrics each funder report needs, and the source fields each metric is calculated from.

How we build

Configure survey structures and data tables in Fineract for each instrument, then map each question to a stored field with a defined type.
Build any scoring or reporting logic as a documented extension or report, and test it against worked examples supplied by your team.
Test data entry on a non-production instance, including partial responses, repeat surveys and edits, before any field team uses the forms.

How we hand over

Deliver a configuration record listing every survey, question, field, permission and report, with the approval owner for each.
Provide a test script and results covering scoring, storage, access restrictions and report totals, so your team can rerun them after changes.
Run a handover session with the data, field operations and funder reporting staff who will use the surveys day to day.

How we support

Support is available as a retainer for survey changes, new funder requirements and checks after Fineract upgrades.
Review survey and report configuration when your instruments change, and retest scoring logic against the agreed examples.
Confirm with your funders and your own compliance team how survey personal data is retained and accessed in your environment.