Mifos X API Documentation

Mifos X is a secure, multi-tenanted microfinance platform.

The goal of the Mifos X API is to empower developers to build apps on top of the Mifos X Platform. The reference Individual Lending app (user: mifos password: password) works on the same demo 'tenant' as the interactive links in this documentation.

The API is organized around REST.

The API is designed to have:
- predictable, resource-oriented URLs
- to use HTTP response codes to indicate API errors
- to use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients.

JSON is returned in all responses from the API, including errors.

Much of the API presentation and design ideas are owed to the excellent Apigee "Web API Design" eBook/PDF and the very good Stripe API reference.

Try The API From Your Browser

GET (read) examples can be run directly from this documentation. It is just a matter of clicking a link. Most browsers display the output on the same page (or another tab if you right click and select that option). Internet Explorer will probably treat the output as if you wanted to download a file. In that case just elect to open the output in a text editor.

If you want to check out the POST, PUT and DELETE (update) examples a good approach is to take a moment to install a REST plugin for your browser e.g. RESTClient for FireFox

The REST plugins will allow you to

Select the "Verb" (e.g. POST)
Enter the resource name (e.g. offices)
Add a header to indicate you are sending JSON data as part of the request body (Content-Type: application/json)
Add a header to indicate your 'tenant' (X-Mifos-Platform-TenantId: default)
Paste the example JSON into a Request Body
Send the Request (and receive a Response)

Generic Options

Convenience Templates

There are a list of convenience resources (see Convenience menu option). These resources end with "/template" and can be useful when building maintenance user interface screens for client applications. The template data returned may consist of any or all of:

Field Defaults
Allowed Value Lists

Also, many "Retrieve a" type resources (Retrieve a Client for example) allow the parameter option "template=true". This appends any "Allowed Value Lists" which can be useful when building update functionality.

Restrict Returned Fields

Parameter "fields={fieldlist}" can be used on GET requests to restrict the fields returned.

Example Request:

offices/1?fields=id,name,parentName

Pretty JSON Formatting

Parameter "pretty=true" can be used to display JSON from GET requests in an easy-to-read format. This parameter is used in this documentation.

Easy-to-read JSON output for POSTs, PUTs and DELETEs will available in the REST plugin you use e.g. RESTClient for FireFox

Creating and Updating

When you want to 'Create a ...' you have to at least supply the mandatory fields. The mandatory fields are listed in this documentation under the relevant 'Create a ...' heading.

When you want to 'Update a ...' you can update individual fields or a combination of fields (subject to data integrity rules).

Updating Dates and Numbers

Dates

Dates are returned in GET requests as an array e.g. [ 2007, 4, 11]. However, they are sent as strings in POST and PUT requests. If there are any dates in your POST or PUT requests, you need to provide the "dateFormat". This can be any date pattern supported by Joda-Time. This capability can help you when saving data in your client application as you shouldn't need to do any date format conversion prior to issuing your POST or PUT request.


JSON examples:
{
 "dateFormat": "dd MMMM yyyy",
 "openingDate": "01 July 2007"
}
{
 "dateFormat": "yyyy-MM-dd",
 "openingDate": "2007-03-21"
}

Numbers

You must provide a "locale" when updating numbers. Numbers are not "Ids" or "Types" but are typically money amounts or percentages that relate to loans. In any case, the API will send back an error message if you forget.


JSON examples:
{
"locale": "en_US",
"principal": "240,400.88"
}
{
"locale": "fr_CH",
"principal": "240 400.88"
}

Field Descriptions

Most fields are self-explanatory. Fields that aren't are described under the relevant resource heading e.g. AUTHENTICATION

Authentication Overview

Authentication to the API occurs via HTTP Basic Auth.

The platform has been configured to reject plain HTTP requests and to expect all API requests to be made over HTTPS. All requests must be authenticated.


//   A Javascript/Jquery example of how to login to Mifos X and use its api.

//   Typically, the javascript application would
//   1) Display a login page to retrieve the username and password.
//   2) Send the username and password to a function
//      such as setBasicAuthKey below which sets the HTTP Basic Auth key.
//   3) The HTTP Basic Auth key is used in all subsequent requests
//      (see the function executeAjaxRequest below).

function setBasicAuthKey(username, password) {
var jqxhr = $.ajax({
        url : "authentication?username=" + username + "&password=" + password,
        type : 'POST',
        contentType : "application/json; charset=utf-8",
        dataType : 'json',
        data : "{}",
        cache : false,
        success : function(data, textStatus, jqXHR) {     
            basicAuthKey = data.base64EncodedAuthenticationKey;
        },
        error : function(jqXHR, textStatus, errorThrown) {
            //error processing
        }
    });
}

function executeAjaxRequest(url, verbType, jsonData, basicAuthKey, successFunction, errorFunction) {
var jqxhr = $.ajax({
        url : url,
        type : verbType, //POST, GET, PUT or DELETE
        contentType : "application/json; charset=utf-8",
        dataType : 'json',
        data : jsonData,
        cache : false,
        beforeSend : function(xhr) {
                xhr.setRequestHeader("Authorization", "Basic " + basicAuthKey);
        },
        success : successFunction,
        error : errorFunction
    });
}

Errors

All errors are returned in JSON.

HTTP Status Code Summary

200 OK - Everything Worked.
400 Bad Request - Invalid Parameter or Data Integrity Issue.
401 Authentication Error.
403 Unauthorized Request.
404 Resource Not Found
500 Platform Internal Server Error.


Error Message returned when attempting to create an Office without passing any parameters
{
    "developerMessage": "The request was invalid. This typically will happen due to validation errors which are provided.",
    "developerDocLink": "https://github.com/keithwoodlock/mifosx/wiki/HTTP-API-Error-codes",
    "httpStatusCode": "400",
    "defaultUserMessage": "Validation errors exist.",
    "userMessageGlobalisationCode": "validation.msg.validation.errors.exist",
    "errors": [
        {
        "developerMessage": "The parameter name cannot be blank.",
        "defaultUserMessage": "The parameter name cannot be blank.",
        "userMessageGlobalisationCode": "validation.msg.office.name.cannot.be.blank",
        "parameterName": "name",
        "value": null,
        "args": []
        },
        {
        "developerMessage": "The parameter openingDate cannot be blank.",
        "defaultUserMessage": "The parameter openingDate cannot be blank.",
        "userMessageGlobalisationCode": "validation.msg.office.openingDate.cannot.be.blank",
        "parameterName": "openingDate",
        "value": null,
        "args": []
        },
        {
        "developerMessage": "The parameter parentId cannot be blank.",
        "defaultUserMessage": "The parameter parentId cannot be blank.",
        "userMessageGlobalisationCode": "validation.msg.office.parentId.cannot.be.blank",
        "parameterName": "parentId",
        "value": null,
        "args": []
        }
            ]
}

Clients

Clients are people and businesses that have applied (or may apply) to an MFI for loans.

Field Descriptions

externalId

A place to put an external reference for this client e.g. The ID another system uses.
If provided, it must be unique.

List Clients

Example Requests:

clients

clients?fields=displayName,officeName,joinedDate

GET https://Domain Name/api/v1/clients

[ {
  "officeId" : 2,
  "officeName" : "sub branch 1",
  "id" : 14,
  "firstname" : "Patrick",
  "lastname" : "Asare-Frimpong",
  "displayName" : "Patrick Asare-Frimpong",
  "externalId" : "123AB",
  "joinedDate" : [ 2012, 4, 18 ]
}, {
  "officeId" : 5,
  "officeName" : "Majmoua",
  "id" : 13,
  "firstname" : "firstMajmoua",
  "lastname" : "client",
  "displayName" : "firstMajmoua client",
  "joinedDate" : [ 2011, 12, 1 ]
}... ]

Retrieve Client Details Template

This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:

Field Defaults
Allowed Value Lists

Example Request:

clients/template

GET https://Domain Name/api/v1/clients/template

{
  "joinedDate" : [ 2012, 5, 29 ],
  "allowedOffices" : [ {
    "id" : 1,
    "name" : "Demo MFI Head Office"
  }, {
    "id" : 2,
    "name" : "sub branch 1"
  }, {
    "id" : 8,
    "name" : "moi aussi"
  }, {
    "id" : 3,
    "name" : "sub branch 2"
  }, {
    "id" : 4,
    "name" : "sub branch 3"
  } ]
}

Retrieve a Client

Example Requests:

clients/1

clients/1?template=true

clients/1?fields=id,displayName,officeName

GET https://Domain Name/api/v1/clients/{clientId}

{
  "officeId" : 1,
  "officeName" : "Demo MFI Head Office",
  "id" : 1,
  "firstname" : "Patrick",
  "lastname" : "O'Meara",
  "displayName" : "Patrick O'Meara",
  "joinedDate" : [ 2009, 1, 4 ]
}

Create a Client

Note: You can enter either:
firstname/lastname - for a person OR
clientOrBusinessName - for a business or organisation (or person known by one name).

Mandatory Fields

firstname and lastname OR clientOrBusinessName
, joinedDate, officeId

POST https://Domain Name/api/v1/clients

POST clients
Content-Type: application/json
Request Body:
{
 "officeId": 1, 
 "firstname": "Petra", 
 "lastname": "Yton", 
 "externalId": "786YYH7",
 "dateFormat": "dd MMMM yyyy",
 "locale": "en",
 "joinedDate": "04 March 2009"
}


{
 "resourceId":23
}

POST clients
Content-Type: application/json
Request Body:
{
 "officeId": 1,
 "clientOrBusinessName": "New Business to Create",
 "externalId": "one/78",
 "dateFormat": "dd MMMM yyyy", 
 "locale": "en",
 "joinedDate": "13 June 2006"
}


{
 "resourceId":26
}

Update a Client

PUT https://Domain Name/api/v1/clients/{clientId}

PUT clients/23
Content-Type: application/json
Request Body:
{ 
 "externalId": "786444UUUYYH7",
 "dateFormat": "dd MMMM yyyy", 
 "locale": "en",
 "joinedDate": "09 June 2006"
}

{ "resourceId": 23}

Retrieve a Client's Loan Account Summary

An example of how a loan portfolio summary can be provided. This one contains quite a bit of redundant data (like the counts) and is requested in a specific use case of the Individual Lending User Interface.
However, it is quite reasonable to add resources like this to simplify User Interface development.

Example Requests:

clients/1/loans

clients/1/loans?fields=openLoans,closedLoans,activeLoanCount

GET https://Domain Name/api/v1/clients/{clientId}/loans

{
  "anyLoanCount": 3,
  "activeLoanCount": 2,
  "openLoans": [
    {
      "id": 22,
      "productId": 1,
      "productName": "Agricultural Loan",
      "status": {
        "id": 300,
        "code": "loanStatusType.active",
        "value": "Active"
      }
    },
    {
      "id": 44,
      "productId": 1,
      "productName": "Agricultural Loan",
      "status": {
        "id": 300,
        "code": "loanStatusType.active",
        "value": "Active"
      }
    }
  ],
  "closedLoanCount": 1,
  "closedLoans": [
    {
      "id": 33,
      "productId": 1,
      "productName": "Agricultural Loan",
      "status": {
        "id": 601,
        "code": "loanStatusType.closed.written.off",
        "value": "Closed (written off)"
      }
    }
  ]
}

Retrieve a Client's Notes

Note: Notes are returned in descending createOn order.

Example Requests:

clients/2/notes

clients/2/notes?fields=note,createdOn,createdByUsername

GET https://Domain Name/api/v1/clients/{clientId}/notes

[ {
  "id" : 20,
  "clientId" : 2,
  "noteType" : {
    "id" : 100,
    "code" : "noteType.client",
    "value" : "Client note"
  },
  "note" : "This is an extra note!",
  "createdById" : 2,
  "createdByUsername" : "super1",
  "createdOn" : 1335066625000,
  "updatedById" : 2,
  "updatedByUsername" : "super1",
  "updatedOn" : 1335066625000
}, {
  "id" : 16,
  "clientId" : 2,
  "noteType" : {
    "id" : 100,
    "code" : "noteType.client",
    "value" : "Client note"
  },
  "note" : "loan only 1/2 amount expected\r\nyes",
  "createdById" : 2,
  "createdByUsername" : "super1",
  "createdOn" : 1334726104000,
  "updatedById" : 2,
  "updatedByUsername" : "super1",
  "updatedOn" : 1335137893000
} ]

Add a Client Note

POST https://Domain Name/api/v1/clients/{clientId}/notes

POST clients/1/notes
Content-Type: application/json
Request Body:
{
"note": "a note about the client"
}

{
 "resourceId": 40
}

Retrieve a Client Note

Example Requests:

clients/2/notes/20

clients/2/notes/20?fields=note,createdOn,createdByUsername

GET https://Domain Name/api/v1/clients/{clientId}/notes/{noteId}

{
  "id" : 20,
  "clientId" : 2,
  "noteType" : {
    "id" : 100,
    "code" : "noteType.client",
    "value" : "Client note"
  },
  "note" : "This is an extra note!",
  "createdById" : 2,
  "createdByUsername" : "super1",
  "createdOn" : 1335066625000,
  "updatedById" : 2,
  "updatedByUsername" : "super1",
  "updatedOn" : 1335066625000
}

Update a Client Note

PUT https://Domain Name/api/v1/clients/{clientId}/notes/{noteId}

PUT clients/2/notes/20
Content-Type: application/json
Request Body:
{
"note": "and here the note is updated nicely."
}

{
 "resourceId": 20
}

Loans

Field Descriptions

principal

Loan amount.

externalId

A place to put an external reference for this loan e.g. The ID another system uses.
If provided, it must be unique.

inArrearsTolerance

The amount that can be 'waived' at end of all loan payments because it is too small to worry about.
This is also the tolerance amount assessed when determining if a loan is in arrears.

numberOfRepayments

Number of installments to repay.
Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType
e.g. 10 (repayments) Every 12 Weeks

interestRatePerPeriod

Interest Rate.
Used like: interestRatePerPeriod% interestRateFrequencyType - interestType
e.g. 12.0000% Per year - Declining Balance

repaymentEvery

Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType
e.g. 10 (repayments) Every 12 Weeks

Each of the items below has an id, code and (english) value.
Only the id (integer) is used when updating. All 3 are returned on GET (read) requests.
The options are fully listed in Retrieve Loan Product Details Template.

repaymentFrequencyType

Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType
e.g. 10 (repayments) Every 12 Weeks
Example Values: Days, Weeks, Months

interestRateFrequencyType

Used like: interestRatePerPeriod% interestRateFrequencyType - interestType
e.g. 12.0000% Per year - Declining Balance
Example Values: Per month, Per year

amortizationType

Example Values: Equal principle payments, Equal installments

interestType

Used like: interestRatePerPeriod% interestRateFrequencyType - interestType
e.g. 12.0000% Per year - Declining Balance
Example Values: Declining Balance, Flat

interestCalculationPeriodType

Example Values: Same as repayment period, Daily

Retrieve Loan Details Template

This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:

Field Defaults
Allowed Value Lists

Arguments

clientId: Integer mandatory
productId: Integer optional; If entered, productId, productName and selectedProduct fields are returned.

Example Requests:

loans/template?clientId=1&productId=1

loans/template?clientId=1

GET https://Domain Name/api/v1/loans/template

{
  "clientId" : 1,
  "clientName" : "Patrick O'Meara",
  "productId" : 1,
  "productName" : "Agricultural Loan",
  "selectedProduct" : {
    "id" : 1,
    "name" : "Agricultural Loan",
    "description" : "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
    "principal" : {
      "currencyCode" : "XOF",
      "digitsAfterDecimal" : 0,
      "amount" : 100000,
      "defaultName" : "CFA Franc BCEAO",
      "nameCode" : "currency.XOF",
      "displaySymbol" : "CFA",
      "zero" : false,
      "greaterThanZero" : true,
      "displaySymbolValue" : "100000 CFA"
    },
    "inArrearsTolerance" : {
      "currencyCode" : "XOF",
      "digitsAfterDecimal" : 0,
      "amount" : 1000,
      "defaultName" : "CFA Franc BCEAO",
      "nameCode" : "currency.XOF",
      "displaySymbol" : "CFA",
      "zero" : false,
      "greaterThanZero" : true,
      "displaySymbolValue" : "1000 CFA"
    },
    "numberOfRepayments" : 1,
    "repaymentEvery" : 12,
    "interestRatePerPeriod" : 1.750000,
    "annualInterestRate" : 21.000000,
    "repaymentFrequencyType" : {
      "id" : 2,
      "code" : "repaymentFrequency.periodFrequencyType.months",
      "value" : "Months"
    },
    "interestRateFrequencyType" : {
      "id" : 2,
      "code" : "interestRateFrequency.periodFrequencyType.months",
      "value" : "Per month"
    },
    "amortizationType" : {
      "id" : 1,
      "code" : "amortizationType.equal.installments",
      "value" : "Equal installments"
    },
    "interestType" : {
      "id" : 0,
      "code" : "interestType.declining.balance",
      "value" : "Declining Balance"
    },
    "interestCalculationPeriodType" : {
      "id" : 1,
      "code" : "interestCalculationPeriodType.same.as.repayment.period",
      "value" : "Same as repayment period"
    },
    "createdOn" : 1334232874000,
    "lastModifedOn" : 1334232874000,
    "currencyOptions" : [ {
      "code" : "KES",
      "name" : "Kenyan Shilling",
      "decimalPlaces" : 2,
      "displaySymbol" : "KSh",
      "nameCode" : "currency.KES",
      "displayLabel" : "Kenyan Shilling (KSh)"
    }, {
      "code" : "BND",
      "name" : "Brunei Dollar",
      "decimalPlaces" : 2,
      "displaySymbol" : "BND",
      "nameCode" : "currency.BND",
      "displayLabel" : "Brunei Dollar (BND)"
    }, {
      "code" : "LBP",
      "name" : "Lebanese Pound",
      "decimalPlaces" : 2,
      "displaySymbol" : "LÂ£",
      "nameCode" : "currency.LBP",
      "displayLabel" : "Lebanese Pound (LÂ£)"
    }, {
      "code" : "GHC",
      "name" : "Ghana Cedi",
      "decimalPlaces" : 2,
      "displaySymbol" : "GHC",
      "nameCode" : "currency.GHC",
      "displayLabel" : "Ghana Cedi (GHC)"
    }, {
      "code" : "USD",
      "name" : "US Dollar",
      "decimalPlaces" : 2,
      "displaySymbol" : "$",
      "nameCode" : "currency.USD",
      "displayLabel" : "US Dollar ($)"
    }, {
      "code" : "XOF",
      "name" : "CFA Franc BCEAO",
      "decimalPlaces" : 0,
      "displaySymbol" : "CFA",
      "nameCode" : "currency.XOF",
      "displayLabel" : "CFA Franc BCEAO (CFA)"
    } ],
    "amortizationTypeOptions" : [ {
      "id" : 1,
      "code" : "amortizationType.equal.installments",
      "value" : "Equal installments"
    }, {
      "id" : 0,
      "code" : "amortizationType.equal.principal",
      "value" : "Equal principle payments"
    } ],
    "interestTypeOptions" : [ {
      "id" : 1,
      "code" : "interestType.flat",
      "value" : "Flat"
    }, {
      "id" : 0,
      "code" : "interestType.declining.balance",
      "value" : "Declining Balance"
    } ],
    "interestCalculationPeriodTypeOptions" : [ {
      "id" : 0,
      "code" : "interestCalculationPeriodType.daily",
      "value" : "Daily"
    }, {
      "id" : 1,
      "code" : "interestCalculationPeriodType.same.as.repayment.period",
      "value" : "Same as repayment period"
    } ],
    "repaymentFrequencyTypeOptions" : [ {
      "id" : 0,
      "code" : "repaymentFrequency.periodFrequencyType.days",
      "value" : "Days"
    }, {
      "id" : 1,
      "code" : "repaymentFrequency.periodFrequencyType.weeks",
      "value" : "Weeks"
    }, {
      "id" : 2,
      "code" : "repaymentFrequency.periodFrequencyType.months",
      "value" : "Months"
    } ],
    "interestRateFrequencyTypeOptions" : [ {
      "id" : 2,
      "code" : "interestRateFrequency.periodFrequencyType.months",
      "value" : "Per month"
    }, {
      "id" : 3,
      "code" : "interestRateFrequency.periodFrequencyType.years",
      "value" : "Per year"
    } ]
  },
  "expectedDisbursementDate" : [ 2012, 6, 7 ],
  "allowedProducts" : [ {
    "id" : 1,
    "name" : "Agricultural Loan"
  }, {
    "id" : 2,
    "name" : "Brunei Loan"
  }, {
    "id" : 3,
    "name" : "IL Loan"
  }, {
    "id" : 4,
    "name" : "IBL Mabeshte"
  }, {
    "id" : 5,
    "name" : "Salary Loan"
  }, {
    "id" : 6,
    "name" : "daily-declining-balance"
  }, {
    "id" : 7,
    "name" : "A new loan product for me"
  } ]
}

Retrieve a Loan

Note: template=true parameter doesn't apply to this resource.

Arguments

associations: optional, Either 'all' or a comma separated list of loan 'associations' (itemised below).; Associations are just extra pieces of data that you might or might not want to retrieve.; 'all': Gets all association data.; 'summary': Loan summary data.; 'repaymentSchedule': Loan Schedule data.; 'loanRepayments': Loan Repayment data.; 'permissions': Data that describes what things can happen to the loan in its current state. Very specific to the needs of the current Individual Lending client application.; 'convenienceData': Some derived data that is specific to the needs of the current Individual Lending client application.

Example Requests:

loans/1

loans/1?fields=id,principal,annualInterestRate

loans/1?associations=all

loans/1?fields=id,principal,annualInterestRate&associations=summary,repaymentSchedule

GET https://Domain Name/api/v1/loans/{loanId}

{
{
  "id": 1,
  "clientId": 1,
  "clientName": "Willie O'Meara",
  "loanProductId": 1,
  "loanProductName": "Agricultural Loan",
  "loanProductDescription": "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
  "status": {
    "id": 100,
    "code": "loanStatusType.submitted.and.pending.approval",
    "value": "Submitted and pending approval"
  },
  "currency": {
    "code": "XOF",
    "name": "CFA Franc BCEAO",
    "decimalPlaces": 0,
    "displaySymbol": "CFA",
    "nameCode": "currency.XOF",
    "displayLabel": "CFA Franc BCEAO (CFA)"
  },
  "principal": 100000,
  "termFrequency": 12,
  "termPeriodFrequencyType": {
    "id": 2,
    "code": "termFrequency.periodFrequencyType.months",
    "value": "Months"
  },
  "numberOfRepayments": 12,
  "repaymentEvery": 1,
  "repaymentFrequencyType": {
    "id": 2,
    "code": "repaymentFrequency.periodFrequencyType.months",
    "value": "Months"
  },
  "transactionProcessingStrategyId": 1,
  "amortizationType": {
    "id": 1,
    "code": "amortizationType.equal.installments",
    "value": "Equal installments"
  },
  "interestRatePerPeriod": 2,
  "interestRateFrequencyType": {
    "id": 2,
    "code": "interestRateFrequency.periodFrequencyType.months",
    "value": "Per month"
  },
  "annualInterestRate": 24,
  "interestType": {
    "id": 0,
    "code": "interestType.declining.balance",
    "value": "Declining Balance"
  },
  "interestCalculationPeriodType": {
    "id": 1,
    "code": "interestCalculationPeriodType.same.as.repayment.period",
    "value": "Same as repayment period"
  },
  "submittedOnDate": [2011,9,20],
  "expectedDisbursementDate": [2011,9,20],
  "expectedMaturityDate": [2012,9,20],
  "lifeCycleStatusDate": [2011,9,20]
}

Create a New Loan / Submit a Loan Application

Arguments

command: String Optional, case-insensitive; The default action is to Submit a New Loan Application ("Submitted and awaiting approval" status).; If "?command=calculateLoanSchedule" is added to the URL then no update is made but the loan schedule (as would have been if the loan had been submitted) is returned. This gives the ability to try out various loan options and 'preview' the schedule before committing to it.

Mandatory Fields

clientId, productId, principal, loanTermFrequency, loanTermFrequencyType, numberOfRepayments, repaymentEvery, repaymentFrequencyType, interestRatePerPeriod, interestRateFrequencyType, amortizationType, interestType, interestCalculationPeriodType, expectedDisbursementDate, submittedOnDate, transactionProcessingStrategyId

POST https://Domain Name/api/v1/loans

POST loans
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en_GB", 
"clientId": 1,
"productId": 1,
"principal": "100,000.00",
"loanTermFrequency": 12,
"loanTermFrequencyType": 2,
"numberOfRepayments": 12,
"repaymentEvery": 1,
"repaymentFrequencyType": 2,
"interestRatePerPeriod": 2,
"interestRateFrequencyType": 2,
"amortizationType": 1,
"interestType": 0,
"interestCalculationPeriodType": 1,
"expectedDisbursementDate": "20 September 2011",
"submittedOnDate": "20 September 2011",
"transactionProcessingStrategyId": 1
}

{
 "resourceId": 42
}

Approve, Undo Approval, Disburse, Undo Disbursal, Reject or Withdraw a Loan Application

Arguments

command: String Mandatory, case-insensitive; 'approve' : Approve Loan; 'disburse' : Disburse Loan; 'reject' : Reject Loan; 'withdrewbyclient' : Client Withdrew Loan Application; 'undoapproval' : Undo Loan Approval; 'undodisbursal' : Undo Loan Disbursal

Mandatory Fields

eventDate

POST https://Domain Name/api/v1/loans/{loanId}

POST loans/1?command=approve
Content-Type: application/json
Request Body:
{
 "dateFormat": "dd MMMM yyyy",
 "eventDate": "07 May 2012",
 "note": "and event note is added"
}


{
"resourceId": 37
}

Delete a Loan

Note: Only loans in "Submitted and awaiting approval" status can be deleted.

DELETE https://Domain Name/api/v1/loans/{loanId}

DELETE loans/1              
Content-Type: application/json
No Request Body:

{
"resourceId": 1
}

Retrieve Loan Repayment/Loan Waiver Template

This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:

Field Defaults
Allowed Value Lists

Arguments

command: String mandatory, case-insensitive; 'repayment'
"date" is set to the date of the first outstanding installment.
"total" "amount" is set to the amount outstanding.; 'waiver'
"date" is set to the current date.
"total" "amount" is set to the remaining loan principal outstanding. The amount that can be waived is limited to the loan's inArrearsTolerance

Example Request:

loans/10/transactions/template?command=repayment

GET https://Domain Name/api/v1/loans/{loanId}/transactions/template"

{
  "transactionType" : {
    "id" : 2,
    "code" : "loanTransactionType.repayment",
    "value" : "Repayment"
  },
  "date" : [ 2009, 8, 1 ],
  "total" : {
    "currencyCode" : "XOF",
    "digitsAfterDecimal" : 0,
    "amount" : 471,
    "defaultName" : "CFA Franc BCEAO",
    "nameCode" : "currency.XOF",
    "displaySymbol" : "CFA",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "471 CFA"
  }
}

Make a Repayment / Loan Waiver

command: String Optional, case-insensitive; 'repayment' : Make Loan Repayment.; 'waiver' : Loan Waiver.

POST https://Domain Name/api/v1/loans/{loanId}/transactions

POST loans/37/transactions?command=repayment
Content-Type: application/json
Request Body:
{
 "locale": "en_GB",
 "dateFormat": "dd MMMM yyyy",
 "transactionDate": "14 May 2012",
 "transactionAmount": "559.88",
 "note": "Repayment at branch"
}

{
"resourceId": 37
}

Retrieve a Repayment or Waiver Details

Example Request:

loans/10/transactions/20

GET https://Domain Name/api/v1/loans/{loanId}/transactions/{transactionId}

{
  "id" : 10,
  "date" : [ 2009, 1, 29 ],
  "total" : {
    "currencyCode" : "XOF",
    "digitsAfterDecimal" : 0,
    "amount" : 300000,
    "defaultName" : "CFA Franc BCEAO",
    "nameCode" : "currency.XOF",
    "displaySymbol" : "CFA",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "300000 CFA"
  },
  "transactionOffsetFromToday" : -1218
}

Adjust a Repayment or Waiver

Note: there is no need to specify command={transactionType} parameter.

Mandatory Fields

transactionDate, transactionAmount

POST https://Domain Name/api/v1/loans/{loanId}/transactions/{transactionId}

POST loans/16/transactions/32
Content-Type: application/json
Request Body:
{
 "locale": "en_GB",
 "dateFormat": "dd MMMM yyyy",
 "transactionDate": "25 May 2012",
 "transactionAmount": "50,000.00",
 "note": "adj note"
}

{
    "resourceId": 16
}

Offices

Offices are used to model an MFIs structure. A hierarchial representation of offices is supported. There will always be at least one office (which represents the MFI or an MFIs head office). All subsequent offices added must have a parent office.

Field Descriptions

externalId

A place to put an external reference for this office e.g. The ID another system uses for it.
If provided, it must be unique.

hierarchy

This field is a system generated convenience field. It can't be set.
It uses "dot notation" to define where an office stands in the office hierarchy.
For example, the system default office (id = 1) has a hierarchy value of '.'
An office (id = 12) placed directly underneath this default office has a hierarchy value of '.12.'
And if a further office (id = 78) is placed directly under office (id = 12) its hierarchy value is '.12.78.'

The hierarchy value is useful when you need to display offices in 'hierarchy' order (perhaps indented in a drop down list box).

List Offices

Example Requests:

offices

offices?fields=id,name,openingDate

GET https://Domain Name/api/v1/offices

[ {
  "id" : 1,
  "name" : "Demo MFI Head Office",
  "externalId" : "1",
  "openingDate" : [ 2009, 1, 1 ],
  "hierarchy" : "."
}, {
  "id" : 2,
  "name" : "B1",
  "openingDate" : [ 2012, 4, 1 ],
  "hierarchy" : ".2.",
  "parentName" : "Demo MFI Head Office",
  "parentId" : 1
}, {
  "id" : 3,
  "name" : "B2",
  "openingDate" : [ 2012, 4, 4 ],
  "hierarchy" : ".3.",
  "parentName" : "Demo MFI Head Office",
  "parentId" : 1
} ]

Retrieve Office Details Template

This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:

Field Defaults
Allowed Value Lists

Example Request:

offices/template

GET https://Domain Name/api/v1/offices/template

{
  "openingDate" : [ 2012, 5, 28 ],
  "allowedParents" : [ {
    "id" : 1,
    "name" : "Demo MFI Head Office"
  }, {
    "id" : 2,
    "name" : "B1"
  }, {
    "id" : 3,
    "name" : "B2"
  } ]
}

Retrieve an Office

Example Requests:

offices/1

offices/1?template=true

offices/1?fields=id,name,parentName

GET https://Domain Name/api/v1/offices/1

{
  "id" : 1,
  "name" : "Demo MFI Head Office",
  "externalId" : "1",
  "openingDate" : [ 2009, 1, 1 ],
  "hierarchy" : "."
}

Create an Office

Mandatory Fields

name, openingDate, parentId

POST https://Domain Name/api/v1/offices

POST offices
Content-Type: application/json 
Request Body:
{
 "name": "Example New Branch",
 "dateFormat": "dd MMMM yyyy",
 "openingDate": "01 July 2007",
 "parentId": 2,
 "externalId": "SYS54-88"
}

{
  "resourceId": 9
}

Update Office

PUT https://Domain Name/api/v1/offices/{officeId}

PUT offices/1
Content-Type: application/json
Request Body:
{
  "name": "Name is updated"
}

{
  "resourceId": 1
}

Loan Products

A Loan product is a template that is used when creating a loan. Much of the template definition can be overridden during loan creation.

Field Descriptions

digitsAfterDecimal

Override the currency default value for digitsAfterDecimal.

principal

Loan amount.

inArrearsTolerance

The amount that can be 'waived' at end of all loan payments because it is too small to worry about.
This is also the tolerance amount assessed when determining if a loan is in arrears.

numberOfRepayments

Number of installments to repay.
Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType
e.g. 10 (repayments) Every 12 Weeks

interestRatePerPeriod

Interest Rate.
Used like: interestRatePerPeriod% interestRateFrequencyType - interestType
e.g. 12.0000% Per year - Declining Balance

repaymentEvery

Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType
e.g. 10 (repayments) Every 12 Weeks

Each of the items below has an id, code and (english) value.
Only the id (integer) is used when updating. All 3 are returned on GET (read) requests.
The options are fully listed in Retrieve Loan Product Details Template.

repaymentFrequencyType

Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType
e.g. 10 (repayments) Every 12 Weeks
Example Values: Days, Weeks, Months

interestRateFrequencyType

Used like: interestRatePerPeriod% interestRateFrequencyType - interestType
e.g. 12.0000% Per year - Declining Balance
Example Values: Per month, Per year

amortizationType

Example Values: Equal principle payments, Equal installments

interestType

Used like: interestRatePerPeriod% interestRateFrequencyType - interestType
e.g. 12.0000% Per year - Declining Balance
Example Values: Declining Balance, Flat

interestCalculationPeriodType

Example Values: Same as repayment period, Daily

List Loan Products

Example Requests:

loanproducts

loanproducts?fields=name,description,interestRateFrequencyType,amortizationType

GET https://Domain Name/api/v1/loanproducts

[ {
  "id" : 1,
  "name" : "Agricultural Loan",
  "description" : "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
  "principal" : {
    "currencyCode" : "XOF",
    "digitsAfterDecimal" : 0,
    "amount" : 100000,
    "defaultName" : "CFA Franc BCEAO",
    "nameCode" : "currency.XOF",
    "displaySymbol" : "CFA",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "100000 CFA"
  },
  "inArrearsTolerance" : {
    "currencyCode" : "XOF",
    "digitsAfterDecimal" : 0,
    "amount" : 1000,
    "defaultName" : "CFA Franc BCEAO",
    "nameCode" : "currency.XOF",
    "displaySymbol" : "CFA",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "1000 CFA"
  },
  "numberOfRepayments" : 1,
  "repaymentEvery" : 12,
  "interestRatePerPeriod" : 1.750000,
  "annualInterestRate" : 21.000000,
  "repaymentFrequencyType" : {
    "id" : 2,
    "code" : "repaymentFrequency.periodFrequencyType.months",
    "value" : "Months"
  },
  "interestRateFrequencyType" : {
    "id" : 2,
    "code" : "interestRateFrequency.periodFrequencyType.months",
    "value" : "Per month"
  },
  "amortizationType" : {
    "id" : 1,
    "code" : "amortizationType.equal.installments",
    "value" : "Equal installments"
  },
  "interestType" : {
    "id" : 0,
    "code" : "interestType.declining.balance",
    "value" : "Declining Balance"
  },
  "interestCalculationPeriodType" : {
    "id" : 1,
    "code" : "interestCalculationPeriodType.same.as.repayment.period",
    "value" : "Same as repayment period"
  },
  "createdOn" : 1334232874000,
  "lastModifedOn" : 1334232874000
}, {
  "id" : 2,
  "name" : "Brunei Loan",
  "principal" : {
    "currencyCode" : "BND",
    "digitsAfterDecimal" : 2,
    "amount" : 76000.00,
    "defaultName" : "Brunei Dollar",
    "nameCode" : "currency.BND",
    "displaySymbol" : "BND",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "76000.00 BND"
  },
  "inArrearsTolerance" : {
    "currencyCode" : "BND",
    "digitsAfterDecimal" : 2,
    "amount" : 50.00,
    "defaultName" : "Brunei Dollar",
    "nameCode" : "currency.BND",
    "displaySymbol" : "BND",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "50.00 BND"
  },
  "numberOfRepayments" : 10,
  "repaymentEvery" : 1,
  "interestRatePerPeriod" : 6.000000,
  "annualInterestRate" : 72.000000,
  "repaymentFrequencyType" : {
    "id" : 1,
    "code" : "repaymentFrequency.periodFrequencyType.weeks",
    "value" : "Weeks"
  },
  "interestRateFrequencyType" : {
    "id" : 2,
    "code" : "interestRateFrequency.periodFrequencyType.months",
    "value" : "Per month"
  },
  "amortizationType" : {
    "id" : 1,
    "code" : "amortizationType.equal.installments",
    "value" : "Equal installments"
  },
  "interestType" : {
    "id" : 0,
    "code" : "interestType.declining.balance",
    "value" : "Declining Balance"
  },
  "interestCalculationPeriodType" : {
    "id" : 1,
    "code" : "interestCalculationPeriodType.same.as.repayment.period",
    "value" : "Same as repayment period"
  },
  "createdOn" : 1334513601000,
  "lastModifedOn" : 1334513601000
}...]

Retrieve Loan Product Details Template

This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:

Field Defaults
Allowed Value Lists

Example Request:

loanproducts/template

GET https://Domain Name/api/v1/loanproducts/template

{
  "principal" : {
    "currencyCode" : "KES",
    "digitsAfterDecimal" : 2,
    "amount" : 0.00,
    "defaultName" : "Kenyan Shilling",
    "nameCode" : "currency.KES",
    "displaySymbol" : "KSh",
    "zero" : true,
    "greaterThanZero" : false,
    "displaySymbolValue" : "0.00 KSh"
  },
  "inArrearsTolerance" : {
    "currencyCode" : "KES",
    "digitsAfterDecimal" : 2,
    "amount" : 0.00,
    "defaultName" : "Kenyan Shilling",
    "nameCode" : "currency.KES",
    "displaySymbol" : "KSh",
    "zero" : true,
    "greaterThanZero" : false,
    "displaySymbolValue" : "0.00 KSh"
  },
  "interestRatePerPeriod" : 0,
  "annualInterestRate" : 0,
  "repaymentFrequencyType" : {
    "id" : 2,
    "code" : "repaymentFrequency.periodFrequencyType.months",
    "value" : "Months"
  },
  "interestRateFrequencyType" : {
    "id" : 2,
    "code" : "interestRateFrequency.periodFrequencyType.months",
    "value" : "Per month"
  },
  "amortizationType" : {
    "id" : 1,
    "code" : "amortizationType.equal.installments",
    "value" : "Equal installments"
  },
  "interestType" : {
    "id" : 0,
    "code" : "interestType.declining.balance",
    "value" : "Declining Balance"
  },
  "interestCalculationPeriodType" : {
    "id" : 1,
    "code" : "interestCalculationPeriodType.same.as.repayment.period",
    "value" : "Same as repayment period"
  },
  "currencyOptions" : [ {
    "code" : "KES",
    "name" : "Kenyan Shilling",
    "decimalPlaces" : 2,
    "displaySymbol" : "KSh",
    "nameCode" : "currency.KES",
    "displayLabel" : "Kenyan Shilling (KSh)"
  }, {
    "code" : "BND",
    "name" : "Brunei Dollar",
    "decimalPlaces" : 2,
    "displaySymbol" : "BND",
    "nameCode" : "currency.BND",
    "displayLabel" : "Brunei Dollar (BND)"
  }, {
    "code" : "LBP",
    "name" : "Lebanese Pound",
    "decimalPlaces" : 2,
    "displaySymbol" : "LÂ£",
    "nameCode" : "currency.LBP",
    "displayLabel" : "Lebanese Pound (LÂ£)"
  }, {
    "code" : "GHC",
    "name" : "Ghana Cedi",
    "decimalPlaces" : 2,
    "displaySymbol" : "GHC",
    "nameCode" : "currency.GHC",
    "displayLabel" : "Ghana Cedi (GHC)"
  }, {
    "code" : "USD",
    "name" : "US Dollar",
    "decimalPlaces" : 2,
    "displaySymbol" : "$",
    "nameCode" : "currency.USD",
    "displayLabel" : "US Dollar ($)"
  }, {
    "code" : "XOF",
    "name" : "CFA Franc BCEAO",
    "decimalPlaces" : 0,
    "displaySymbol" : "CFA",
    "nameCode" : "currency.XOF",
    "displayLabel" : "CFA Franc BCEAO (CFA)"
  } ],
  "amortizationTypeOptions" : [ {
    "id" : 1,
    "code" : "amortizationType.equal.installments",
    "value" : "Equal installments"
  }, {
    "id" : 0,
    "code" : "amortizationType.equal.principal",
    "value" : "Equal principle payments"
  } ],
  "interestTypeOptions" : [ {
    "id" : 1,
    "code" : "interestType.flat",
    "value" : "Flat"
  }, {
    "id" : 0,
    "code" : "interestType.declining.balance",
    "value" : "Declining Balance"
  } ],
  "interestCalculationPeriodTypeOptions" : [ {
    "id" : 0,
    "code" : "interestCalculationPeriodType.daily",
    "value" : "Daily"
  }, {
    "id" : 1,
    "code" : "interestCalculationPeriodType.same.as.repayment.period",
    "value" : "Same as repayment period"
  } ],
  "repaymentFrequencyTypeOptions" : [ {
    "id" : 0,
    "code" : "repaymentFrequency.periodFrequencyType.days",
    "value" : "Days"
  }, {
    "id" : 1,
    "code" : "repaymentFrequency.periodFrequencyType.weeks",
    "value" : "Weeks"
  }, {
    "id" : 2,
    "code" : "repaymentFrequency.periodFrequencyType.months",
    "value" : "Months"
  } ],
  "interestRateFrequencyTypeOptions" : [ {
    "id" : 2,
    "code" : "interestRateFrequency.periodFrequencyType.months",
    "value" : "Per month"
  }, {
    "id" : 3,
    "code" : "interestRateFrequency.periodFrequencyType.years",
    "value" : "Per year"
  } ]
}

Retrieve a Loan Product

Example Requests:

loanproducts/1

loanproducts/1?template=true

loanproducts/1?fields=name,description,numberOfRepayments

GET https://Domain Name/api/v1/loanproducts/{productId}

{
  "id" : 1,
  "name" : "Agricultural Loan",
  "description" : "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
  "principal" : {
    "currencyCode" : "XOF",
    "digitsAfterDecimal" : 0,
    "amount" : 100000,
    "defaultName" : "CFA Franc BCEAO",
    "nameCode" : "currency.XOF",
    "displaySymbol" : "CFA",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "100000 CFA"
  },
  "inArrearsTolerance" : {
    "currencyCode" : "XOF",
    "digitsAfterDecimal" : 0,
    "amount" : 1000,
    "defaultName" : "CFA Franc BCEAO",
    "nameCode" : "currency.XOF",
    "displaySymbol" : "CFA",
    "zero" : false,
    "greaterThanZero" : true,
    "displaySymbolValue" : "1000 CFA"
  },
  "numberOfRepayments" : 1,
  "repaymentEvery" : 12,
  "interestRatePerPeriod" : 1.750000,
  "annualInterestRate" : 21.000000,
  "repaymentFrequencyType" : {
    "id" : 2,
    "code" : "repaymentFrequency.periodFrequencyType.months",
    "value" : "Months"
  },
  "interestRateFrequencyType" : {
    "id" : 2,
    "code" : "interestRateFrequency.periodFrequencyType.months",
    "value" : "Per month"
  },
  "amortizationType" : {
    "id" : 1,
    "code" : "amortizationType.equal.installments",
    "value" : "Equal installments"
  },
  "interestType" : {
    "id" : 0,
    "code" : "interestType.declining.balance",
    "value" : "Declining Balance"
  },
  "interestCalculationPeriodType" : {
    "id" : 1,
    "code" : "interestCalculationPeriodType.same.as.repayment.period",
    "value" : "Same as repayment period"
  },
  "createdOn" : 1334232874000,
  "lastModifedOn" : 1334232874000
}

Create a Loan Product

Mandatory Fields

name, currencyCode, digitsAfterDecimal, principal, inArrearsTolerance, repaymentFrequencyType, repaymentEvery, numberOfRepayments, interestRatePerPeriod, interestRateFrequencyType, amortizationType, interestType, interestCalculationPeriodType

POST https://Domain Name/api/v1/loanproducts

POST loanproducts
Content-Type: application/json
Request Body:
{
 "name": "A new loan product for me",
 "description": "A description not exceeding 500 characters.",
 "currencyCode": "USD",
 "digitsAfterDecimal": "2",
 "locale": "en_GB",
 "principal": "100,000.00",
 "inArrearsTolerance": "1,000.00",
 "repaymentFrequencyType": 2,
 "repaymentEvery": "1",
 "numberOfRepayments": "12",
 "interestRatePerPeriod": "1.75",
 "interestRateFrequencyType": 2,
 "amortizationType": 1,
 "interestType": 0,
 "interestCalculationPeriodType": 1
}

{
  "resourceId": 9
}

Update a Loan Product

POST https://Domain Name/api/v1/loanproducts/{loanId}

POST loanproducts/1
Content-Type: application/json
Request Body:
{
 "locale": "en_GB",
 "principal": "100,000.00",
 "inArrearsTolerance": "5,000.00"
}

{
  "resourceId": 1
}

Configuration

Application related configuration. For example, selecting the currencies permitted for use within the MFI.

Retrieve Currency Configuration

Returns the list of currencies permitted for use AND the list of currencies not selected (but available for selection).

Example Requests:

configurations/currency

configurations/currency?fields=selectedCurrencyOptions

GET https://Domain Name/api/v1/configurations/currency

{
  "selectedCurrencyOptions" : [ {
    "code" : "XOF",
    "name" : "CFA Franc BCEAO",
    "decimalPlaces" : 0,
    "displaySymbol" : "CFA",
    "nameCode" : "currency.XOF",
    "displayLabel" : "CFA Franc BCEAO (CFA)"
  }, {
    "code" : "ETB",
    "name" : "Ethiopian Birr",
    "decimalPlaces" : 2,
    "nameCode" : "currency.ETB",
    "displayLabel" : "Ethiopian Birr [ETB]"
  } ],
  "currencyOptions" : [ {
    "code" : "AED",
    "name" : "UAE Dirham",
    "decimalPlaces" : 2,
    "nameCode" : "currency.AED",
    "displayLabel" : "UAE Dirham [AED]"
  }, {
    "code" : "AFN",
    "name" : "Afghanistan Afghani",
    "decimalPlaces" : 2,
    "nameCode" : "currency.AFN",
    "displayLabel" : "Afghanistan Afghani [AFN]"
  }, ...
 ]
}

Update Currency Configuration

Updates the list of currencies permitted for use.

PUT https://Domain Name/api/v1/configurations/currency

PUT configurations/currency
Content-Type: application/json
Request Body:{
"currencies": ["KES", "BND",  "LBP", "GHC", "USD", "XOF", "AED", "AMD"]
}

{
    "currencies": [
    "KES",
    "BND",
    "LBP",
    "GHC",
    "USD",
    "XOF",
    "AED",
    "AMD"
    ]
}

Data Tables

The datatables API allows you to plug-in your own tables (MySql) that have a relationship to a Mifos X core table. For example, you might want to add some extra client fields and record information about each of the clients' family members. Via the API you can create, read, update and delete entries for each 'plugged-in' table. The API checks for permission and for 'data scoping' (only data within the users' office hierarchy can be managed by the user).

The Mifos X Reference App uses a JQuery plugin called stretchydatatables (which in turn uses this datatables resource) to provide a pretty flexible CRUD (Create, Read, Update, Delete) User Interface.

List Data Tables

Lists registered data tables and the Mifos X Core application table they are registered to.

Arguments

apptable: optional; The Mifos X core application table.

Example Requests:

datatables?apptable=m_client

datatables

GET https://Domain Name/api/v1/datatables

[
  {
    "applicationTableName": "m_client",
    "registeredTableName": "Additional Client Fields Data"
  },
  {
    "applicationTableName": "m_client",
    "registeredTableName": "Extra Family Details Data"
  },
  {
    "applicationTableName": "m_loan",
    "registeredTableName": "Additional Loan Fields Data"
  }
]

Register Data Table

Registers a data table with the Mifos X Core application table. This allows the data table to be maintained through the API.

POST https://Domain Name/api/v1/datatables/register/{datatable}/{apptable}

POST datatables/register/New Table/m_client
Content-Type: application/json
Request Body:
{
}

{
  "resourceId": null
}

Deregister Data Table

Deregisters a data table. It will no longer be available through the API.

POST https://Domain Name/api/v1/datatables/deregister/{datatable}

POST datatables/register/New Table
Content-Type: application/json
Request Body:
{
}

{
  "resourceId": null
}

Create Entry in Data Table

Adds a row to the data table.

Note that the default datatable UI functionality converts any field name containing spaces to underscores when using the API. This means the field name "Business Description" is considered the same as "Business_Description". So you shouldn't have both "versions" in any data table.

POST https://Domain Name/api/v1/datatables/{datatable}/{apptableId}

POST datatables/Additional Client Fields Data/1
Content-Type: application/json
Request Body:
{
    "Business Description": "Livestock sales",
    Comment: "First comment\nmade",
    Education_cv: "Trade",
    Gender_cd: "21",
    "Highest Rate Paid": "8.5",
    "Next Visit": "01 October 2012",
    "Years in Business": "5",
    dateFormat: "dd MMMM yyyy",
    locale: "en"
}

{
  "resourceId": 1
}

Retrieve Entry(s) from Data Table

Gets the entry (if it exists) for data tables that are one to one with the application table.
Gets the entries (if they exist) for data tables that are one to many with the application table.

Note: The 'fields' parameter is not available for datatables.

Arguments

order: optional; Specifies the order in which data is returned.
genericResultSet: optional; If 'true' a Generic Result Set JSON format is returned. This format is used by the default data tables UI functionality.

Example Requests:

datatables/Additional Client Fields Data/1

datatables/Extra Family Details Data/1?order=`Date of Birth` desc

datatables/Additional Client Fields Data/1?genericResultSet=true

GET https://Domain Name/api/v1/datatables/{datatable}/{apptableId}

[
{"client_id": 1,
"Business Description": "Livestock sales",
"Years in Business": 5,
"Gender_cd": "21",
"Education_cv": "Trade",
"Next Visit": [2012, 10, 1],
"Highest Rate Paid": 8.500000,
"Comment": "First comment
made"}
]

Update Entry in Data Table (One to One)

Updates the row (if it exists) of the data table.

PUT https://Domain Name/api/v1/datatables/{datatable}/{apptableId}

PUT datatables/Additional Client Fields Data/1
Content-Type: application/json
Request Body:
{
    "Business Description": "Livestock sales updated",
    Comment: "First comment\nmade",
    Education_cv: "Trade",
    Gender_cd: "21",
    "Highest Rate Paid": "8.5",
    "Next Visit": "01 October 2012",
    "Years in Business": "5",
    dateFormat: "dd MMMM yyyy",
    locale: "en"
}

{
  "resourceId": 1
}

Update Entry in Data Table (One to Many)

Updates the row (if it exists) of the data table.

PUT https://Domain Name/api/v1/datatables/{datatable}/{apptableId}/{datatableId}

PUT datatables/Extra Family Details Data/1/2
Content-Type: application/json
Request Body:
{
    "Date of Birth": "01 June 1982",
    Education_cdHighest: "5",
    Name: "June",
    "Other Notes": "More\nnotes",
    "Points Score": "20",
    dateFormat: "dd MMMM yyyy",
    locale: "en"	
}

{
  "resourceId": 1
}

Delete Entry(s) in Data Table

Deletes the entry (if it exists) for data tables that are one to one with the application table.
Deletes the entries (if they exist) for data tables that are one to many with the application table.

DELETE https://Domain Name/api/v1/datatables/{datatable}/{apptableId}

DELETE datatables/Additional Client Fields Data/1
Content-Type: application/json
Request Body:
{
}

{
  "resourceId": 1
}

Delete Entry in Data Table (One to Many)

Deletes the entry (if it exists) for data tables that are one to many with the application table.

DELETE https://Domain Name/api/v1/datatables/{datatable}/{apptableId}/{datatableId}

DELETE datatables/Extra Family Details Data/1/2
Content-Type: application/json
Request Body:
{
}

{
  "resourceId": 1
}

Reports

The reports resource allows you to run and receive output from pre-defined Mifos X reports. The default output is a JSON formatted "Generic Resultset". The Generic Resultset contains Column Heading as well as Data information. However, you can export to CSV format by simply adding "&exportCSV=true" to the end of your URL.

If Pentaho reports have been pre-defined, they can also be run through this resource. Pentaho reports can return HTML, PDF or CSV formats.

The Mifos X Individual Lending client application uses a JQuery plugin called stretchyreporting which, itself, uses this reports resource to provide a pretty flexible reporting User Interface (UI).

List Reports

Lists all reports and their parameters. If a report has more than one parameter it will be listed the same number of times as it has parameters.

Arguments

exportCSV: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Output will be delivered as a CSV file instead of JSON.

Example Requests:

reports

reports?exportCSV=true

GET https://Domain Name/api/v1/reports

{
  "columnHeaders" : [ {
    "columnName" : "report_id",
    "columnType" : "INT",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "report_name",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "report_type",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "report_subtype",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "report_category",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "parameter_id",
    "columnType" : "INT",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "report_parameter_name",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "parameter_name",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  } ],
  "data" : [ {
    "row" : [ "29", "Client Listing", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "42", "Client Listing - Additional and Unlikely", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "30", "Client Loans Listing", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "43", "Client Loans Listing - Additional", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "41", "Clients by Surname (a bit silly)", "Chart", "Pie", null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "39", "Loan Disbursals in Previous Year", "Chart", "Bar", null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "39", "Loan Disbursals in Previous Year", "Chart", "Bar", null, "7", null, "currencyIdSelectOne" ]
  }, {
    "row" : [ "40", "Loan Repayments in Previous Year", "Chart", "Bar", null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "40", "Loan Repayments in Previous Year", "Chart", "Bar", null, "7", null, "currencyIdSelectOne" ]
  }, {
    "row" : [ "34", "Loans - Active Loans Portfolio Status", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "34", "Loans - Active Loans Portfolio Status", "Table", null, null, "6", null, "currencyIdSelectAll" ]
  }, {
    "row" : [ "31", "Loans Awaiting Disbursal", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "35", "Portfolio at Risk", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "35", "Portfolio at Risk", "Table", null, null, "6", null, "currencyIdSelectAll" ]
  }, {
    "row" : [ "32", "Upcoming Repayments", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "32", "Upcoming Repayments", "Table", null, null, "6", null, "currencyIdSelectAll" ]
  }, {
    "row" : [ "38", "Upcoming Repayments Summary By Month, Currency and Loan Risk", "Table", null, null, "5", null, "selectOfficeId" ]
  }, {
    "row" : [ "38", "Upcoming Repayments Summary By Month, Currency and Loan Risk", "Table", null, null, "6", null, "currencyIdSelectAll" ]
  } ]
}

Running a Report

Runs a report and returns the report output.

Arguments

R_'parameter names' ...: optional, No defaults; The number and names of the parameters depend on the specific report and how it has been configured. R_officeId is an example parameter name.; Note: the prefix R_ stands for Reporting
parameterType: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Determines whether the request looks in the list of reports or the list of parameters for its data. Doesn't apply to Pentaho reports.
exportCSV: optional, The only valid value is 'true'. If any other value is provided the argument will be ignored; Output will be delivered as a CSV file instead of JSON. Doesn't apply to Pentaho reports.
output-type: optional, Defaults to HTML.; Valid Values are HTML, XLS, CSV and PDF for html, Excel, CSV and PDF formats respectively.; Only applies to Pentaho reports.

Example Requests:

reports/Client%20Listing?R_officeId=1

reports/Client%20Listing?R_officeId=1&exportCSV=true

reports/selectOfficeId?R_officeId=1&parameterType=true

reports/selectOfficeId?R_officeId=1&parameterType=true&exportCSV=true

reports/Client Listing (Pentaho)?output-type=HTML&R_officeId=1

reports/Client Listing (Pentaho)?output-type=XLS&R_officeId=1

reports/Client Listing (Pentaho)?output-type=CSV&R_officeId=1

reports/Client Listing (Pentaho)?output-type=PDF&R_officeId=1

GET https://Domain Name/api/v1/reports/{reportName}

{
  "columnHeaders" : [ {
    "columnName" : "Office/Branch",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "Name",
    "columnType" : "VARCHAR",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  }, {
    "columnName" : "Joining Date",
    "columnType" : "DATE",
    "columnLength" : null,
    "columnDisplayType" : null,
    "columnValues" : [ ]
  } ],
  "data" : [ {
    "row" : [ "Demo MFI Head Office", "O'Meara, Patrick", "2009-01-04" ]
  }, {
    "row" : [ "Demo MFI Head Office", "O'Meara, Dennis", "2009-01-04" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Smith, John", "2009-01-11" ]
  }, {
    "row" : [ "Demo MFI Head Office", "O'Meara, Jimmy", "2009-01-11" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Sunnyville vegetable growers Ltd", "2009-01-24" ]
  }, {
    "row" : [ "Demo MFI Head Office", "TraorÃ©, Kalilou", "2009-02-04" ]
  }, {
    "row" : [ "Demo MFI Head Office", "KonÃ©, Sidi", "2009-02-11" ]
  }, {
    "row" : [ "Demo MFI Head Office", "YattabarÃ©, Moustapha", "2009-02-18" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Mali fruit sales ltd.", "2009-02-18" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Djenne co-op group", "2009-02-25" ]
  }, {
    "row" : [ "Demo MFI Head Office", "test, test", "2012-04-19" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Ziffle, Fred", "2012-04-21" ]
  }, {
    "row" : [ "Demo MFI Head Office", "omara, safik", "2012-04-24" ]
  }, {
    "row" : [ "Demo MFI Head Office", "HF Test", "2012-04-24" ]
  }, {
    "row" : [ "Demo MFI Head Office", "HF Test 2", "2012-04-24" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Kumar, Shiva", "2011-10-01" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Yton, Petra", "2006-06-09" ]
  }, {
    "row" : [ "Demo MFI Head Office", "Yton, Petra", "2006-06-09" ]
  }, {
    "row" : [ "sub branch 1", "Lee, Jacques", "2012-04-03" ]
  }, {
    "row" : [ "sub branch 1", "Asare-Frimpong, Patrick", "2012-04-18" ]
  }, {
    "row" : [ "sub branch 2", "t, test", "2012-04-18" ]
  }, {
    "row" : [ "Majmoua", "client, firstMajmoua", "2011-12-01" ]
  }, {
    "row" : [ "Intrasoft Technologies", "Said, Zayyad", "2012-04-02" ]
  }, {
    "row" : [ "Hugo technologies", "typical individual lending client", "2010-06-02" ]
  } ]
}

Authentication

An API capability that allows client applications to verify authentication details.

Field Descriptions

base64EncodedAuthenticationKey

HTTP Basic Auth key. See Authentication Overview for an example of its use.

Verify authentication

Authenticates the credentials provided and returns the set of permissions allowed.

POST https://Domain Name/api/v1/authentication?username={username}&password={password}

POST authentication?username=super1&password=demo
Content-Type: application/json
No Request Body

{
    "username": "super1",
    "userId": 2,
    "base64EncodedAuthenticationKey": "c3VwZXIxOmRlbW8=",
    "authenticated": true,
    "permissions": [
    "USER_ADMINISTRATION_SUPER_USER_ROLE",
    "REPORTING_SUPER_USER_ROLE",
    "PORTFOLIO_MANAGEMENT_SUPER_USER_ROLE",
    "ORGANISATION_ADMINISTRATION_SUPER_USER_ROLE"
    ]
}

Users

An API capability to support user administration.

Retrieve list of users

Example Requests:

users

users?fields=id,username,email,officeName

GET https://Domain Name/api/v1/users

[ {
  "id" : 6,
  "officeId" : 1,
  "officeName" : "change super user",
  "username" : "committee1",
  "firstname" : "Committee",
  "lastname" : "Member",
  "email" : "fake@email.com"
}, {
  "id" : 5,
  "officeId" : 1,
  "officeName" : "change super user",
  "username" : "dataentry1",
  "firstname" : "Data Entry",
  "lastname" : "User",
  "email" : "fake@email.com"
}...]

Retrieve User Details Template

This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:

Field Defaults
Allowed Value Lists

Example Request:

users/template

GET https://Domain Name/api/v1/users/template

{
  "allowedOffices": [
    {
      "id": 1,
      "name": "Head Office",
      "nameDecorated": "Head Office"
    },
    {
      "id": 10,
      "name": "Myanmar Regional Office",
      "nameDecorated": "....Myanmar Regional Office"
    },
    {
      "id": 7,
      "name": "Myanmar 1",
      "nameDecorated": "........Myanmar 1"
    },...
  ],
  "availableRoles": [
    {
      "id": 1,
      "name": "Super user",
      "description": "This role provides all application permissions."
    },
    {
      "id": 2,
      "name": "Field officer",
      "description": "A field officer role allows the user to add client and loans and view reports but nothing else."
    },
    {
      "id": 3,
      "name": "Data Entry (Portfolio only)",
      "description": "This role allows a user full permissions around client and loan functionality but nothing else."
    },...
  ],
  "selectedRoles": []
}

Retrieve a User

Example Requests:

users/1

users/1?template=true

users/1?fields=username,officeName

GET https://Domain Name/api/v1/users/1

{
  "id": 1,
  "username": "mifos",
  "officeId": 1,
  "officeName": "Head Office",
  "firstname": "App(test)",
  "lastname": "Administrator",
  "email": "demomfi@mifos.org",
  "allowedOffices": [],
  "availableRoles": [
    {
      "id": 2,
      "name": "Field officer",
      "description": "A field officer role allows the user to add client and loans and view reports but nothing else."
    },
    {
      "id": 3,
      "name": "Data Entry (Portfolio only)",
      "description": "This role allows a user full permissions around client and loan functionality but nothing else."
    },...
  ],
  "selectedRoles": [
    {
      "id": 1,
      "name": "Super user",
      "description": "This role provides all application permissions."
    }
  ]
}

Create a User

Adds new application user.

Note: Password information is not required (or processed). Password details are auto-generated and then sent to the email account given (which is why it can take a few seconds to complete).

Mandatory Fields

username, firstname, lastname, email, officeId, roles

POST https://Domain Name/api/v1/users

POST users
Content-Type: application/json
Request body:
{ 
 "username": "Another New User zll", 
 "firstname": "Test", 
 "lastname": "User", 
 "email": "whatever@mifos.org", 
 "officeId": 1, 
 "roles": [2,3] 
}


{
  "resourceId": 11
}

Update a User

Note: When updating a password you must provide the repeatPassword parameter also.

PUT https://Domain Name/api/v1/users/{userId)

PUT users/3
Content-Type: application/json
Request body:
{
 "firstname": "Test", 
 "roles": [2], 
 "password": "window75", 
 "repeatPassword": "window75"
}


{
  "resourceId": 3
}

Delete a User

Removes the user and the associated roles and permissions.

DELETE https://Domain Name/api/v1/users/{userId}

DELETE users/20
Content-Type: application/json
No Request Body

{
 "resourceId": 20
}

Roles

An API capability to support management of application roles for user administration.

List Roles

Example Requests:

roles

roles?fields=name

GET https://Domain Name/api/v1/roles

[ {
  "id" : 1,
  "name" : "Super user",
  "description" : "This role provides all application permissions."
}, {
  "id" : 2,
  "name" : "Field officer",
  "description" : "A field officer role allows the user to add client and loans and view reports but nothing else."
}, {
  "id" : 3,
  "name" : "Data Entry (Portfolio only)",
  "description" : "This role allows a user full permissions around client and loan functionality but nothing else."
}, {
  "id" : 4,
  "name" : "Credit Committe Member",
  "description" : "This role allows a user to approve reject or withdraw loans (with reporting)."
}, {
  "id" : 5,
  "name" : "Manager",
  "description" : "This role allows a manager to do anything related to portfolio management and also view all reports."
} ]

Retrieve a Role

Example Requests:

roles/1

roles/1?fields=name

GET https://Domain Name/api/v1/roles/{roleId}

{
  "id" : 1,
  "name" : "Super user",
  "description" : "This role provides all application permissions."
}

Create a New Role

Mandatory Fields

name, description

POST https://Domain Name/api/v1/roles

POST roles
Content-Type: application/json
Request body:
{ 
 "name": "Another Role Name", 
 "description": "A description outlining the purpose of this role in relation to the application."
}

{
  "resourceId": 8
}

Update a Role

PUT https://Domain Name/api/v1/roles/{roleId}

PUT roles/8
Content-Type: application/json
Request body:
{ 
 "name": "Updated Role Name"
}

{
  "resourceId": 8
}

Retrieve a Role's Permissions

Example Requests:

roles/1/permissions

GET https://Domain Name/api/v1/roles/{roleId}/permissions

{
  "id": 1,
  "name": "Super user",
  "description": "This role provides all application permissions.",
  "permissionUsageData": [
    {
      "grouping": "authorisation",
      "code": "READ_PERMISSION",
      "entityName": "PERMISSION",
      "actionName": "READ",
      "selected": false,
      "isMakerChecker": false
    },
    {
      "grouping": "authorisation",
      "code": "CREATE_ROLE",
      "entityName": "ROLE",
      "actionName": "CREATE",
      "selected": false,
      "isMakerChecker": false
    },
    {
      "grouping": "authorisation",
      "code": "DELETE_ROLE",
      "entityName": "ROLE",
      "actionName": "DELETE",
      "selected": false,
      "isMakerChecker": false
    },...]
}

Update a Role's Permissions

PUT https://Domain Name/api/v1/roles/{roleId}/permissions

PUT roles/8
Content-Type: application/json
Request body:
{
ADJUST_LOAN: "true",
ALL_FUNCTIONS: "true",
ALL_FUNCTIONS_READ: "true"
}

{
  "resourceId": 8
}

Permissions

An API capability to support management of application permissions for user administration.

List Application Permissions

Example Requests:

permissions

permissions?fields=grouping,code

GET https://Domain Name/api/v1/permissions

[
  {
    "grouping": "authorisation",
    "code": "READ_PERMISSION",
    "entityName": "PERMISSION",
    "actionName": "READ",
    "selected": true,
    "isMakerChecker": false
  },
  {
    "grouping": "authorisation",
    "code": "CREATE_ROLE",
    "entityName": "ROLE",
    "actionName": "CREATE",
    "selected": true,
    "isMakerChecker": true
  },
  {
    "grouping": "authorisation",
    "code": "DELETE_ROLE",
    "entityName": "ROLE",
    "actionName": "DELETE",
    "selected": true,
    "isMakerChecker": true
  }, ... ]

Overview

Core

Configuration

Non-Core Data

Report

User Related

Convenience