-
-
-
-
-
- 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 app (username: 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.
-Normal Request:
-offices/1
-
- Request (restricting fields returned):
-offices/1?fields=id,name
-
- 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
-Normal Request (with pretty printing/formatting):
-offices/1?pretty=true
-
-
-
-
-
-
-
-
-
- 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, the API accepts them as strings in POST and PUT requests. - If there are any dates in your POST or PUT requests, you need to provide the "locale" and "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:
-{
- "locale": "en_US",
- "dateFormat": "dd MMMM yyyy",
- "openingDate": "01 July 2007"
-}
-{
- "locale": "en_US",
- "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.
+
+
+
+
+ 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 app
+ (username: 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.
+
+
+
-// 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).
+
+
+
+ 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)
+
+
+
-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
- }
- });
-}
+
+
+
+ Generic Options
+ Convenience Templates
+ There are a list of convenience resources (see Template
+ 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.
+
-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 accountNo If provided during client creation, its value is set as account no. for client account, otherwise an auto generated account no. is put in place based on the configured strategy. firstname Facility to break up name into parts suitable for humans. middlename Facility to break up name into parts suitable for humans. lastname Facility to break up name into parts suitable for humans. fullname Facility to set name of a client or business that doesnt suit the firstname,middlename,lastname structure. 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
-[
- {
- "id": 2,
- "accountNo": "000000002",
- "externalId": "one/78",
- "fullname": "New Business to Create",
- "displayName": "New Business to Create",
- "officeId": 1,
- "officeName": "Head Office",
- "joinedDate": [
- 2006,
- 6,
- 13
- ]
- },
- {
- "id": 1,
- "accountNo": "000000001",
- "externalId": "786YYH7",
- "firstname": "Petra",
- "lastname": "Yton",
- "displayName": "Petra Yton",
- "officeId": 1,
- "officeName": "Head Office",
- "joinedDate": [
- 2009,
- 3,
- 4
- ]
- }
-]
-
-
-
-
-
-
-
- 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
-{
- "officeId": 1,
- "joinedDate": [ 2013, 2, 5],
- "allowedOffices": [
- {
- "id": 1,
- "name": "Head Office",
- "nameDecorated": "Head Office"
- }
- ]
-}
-
-
-
-
-
-
-
-
- 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}
-{
- "id": 1,
- "accountNo": "000000001",
- "externalId": "786YYH7",
- "firstname": "Petra",
- "lastname": "Yton",
- "displayName": "Petra Yton",
- "officeId": 1,
- "officeName": "Head Office",
- "joinedDate": [
- 2009,
- 3,
- 4
- ]
-}
-
-
-
-
-
-
-
- Create a Client
- Note: You can enter either:
- firstname/middlename/lastname - for a person (middlename is optional) OR
- fullname - for a business or organisation (or person known by one name).
-
-
- Mandatory Fields firstname and lastname OR fullname
, 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"
-}
-
-{
- "officeId": 1,
- "clientId": 1,
- "resourceId": 1
-}
-
-
-
-POST clients
-Content-Type: application/json
-Request Body:
-{
- "officeId": 1,
- "fullname": "New Business to Create",
- "externalId": "one/78",
- "dateFormat": "dd MMMM yyyy",
- "locale": "en",
- "joinedDate": "13 June 2006"
-}
-
-{
- "officeId": 1,
- "clientId": 2,
- "resourceId": 2
-}
-
-
-
+ Restrict Returned Fields
+ Parameter "fields={fieldlist}" can be used on GET requests
+ to restrict the fields returned.
+ Normal Request:
+ offices/1
+
+ Request (restricting fields returned):
+ offices/1?fields=id,name
+
+ 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
+ Normal Request (with pretty printing/formatting):
+ offices/1?pretty=true
+
+
-
-
-
- Update a Client
-
-
- PUT https://Domain Name/api/v1/clients/{clientId}
-PUT clients/1
-Content-Type: application/json
-Request Body:
-{
- "externalId": "786444UUUYYH7",
- "dateFormat": "dd MMMM yyyy",
- "locale": "en",
- "joinedDate": "09 June 2006"
-}
-
-{
- "officeId": 1,
- "clientId": 1,
- "resourceId": 1,
- "changes": {
- "externalId": "786444UUUYYH7",
- "joinedDate": "09 June 2006",
- "dateFormat": "dd MMMM yyyy",
- "locale": "en"
- }
-}
-
-
-
-
-
-
-
- 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": 9,
- "pendingApprovalLoanCount": 4,
- "pendingApprovalLoans": [
- {
- "id": 48,
- "accountNo": "48",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 100,
- "code": "loanStatusType.submitted.and.pending.approval",
- "value": "Submitted and pending approval"
- }
- },
- {
- "id": 50,
- "accountNo": "50",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 100,
- "code": "loanStatusType.submitted.and.pending.approval",
- "value": "Submitted and pending approval"
- }
- },
- {
- "id": 51,
- "accountNo": "51",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 100,
- "code": "loanStatusType.submitted.and.pending.approval",
- "value": "Submitted and pending approval"
- }
- },
- {
- "id": 62,
- "accountNo": "62",
- "productId": 3,
- "productName": "Further Loan Product",
- "status": {
- "id": 100,
- "code": "loanStatusType.submitted.and.pending.approval",
- "value": "Submitted and pending approval"
- }
- }
- ],
- "activeLoanCount": 2,
- "openLoans": [
- {
- "id": 46,
- "accountNo": "46",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 300,
- "code": "loanStatusType.active",
- "value": "Active"
- }
- },
- {
- "id": 60,
- "accountNo": "60",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 300,
- "code": "loanStatusType.active",
- "value": "Active"
- }
- }
- ],
- "closedLoanCount": 3,
- "closedLoans": [
- {
- "id": 22,
- "accountNo": "22",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 700,
- "code": "loanStatusType.overpaid",
- "value": "Overpaid"
- }
- },
- {
- "id": 33,
- "accountNo": "33",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 601,
- "code": "loanStatusType.closed.written.off",
- "value": "Closed (written off)"
- }
- },
- {
- "id": 44,
- "accountNo": "44",
- "productId": 1,
- "productName": "PORetailLoan",
- "status": {
- "id": 600,
- "code": "loanStatusType.closed.obligations.met",
- "value": "Closed (obligations met)"
- }
- }
- ]
-}
-
-
-
+
-
-
-
-
-
-
- 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": 2,
- "clientId": 1,
- "noteType": {
- "id": 100,
- "code": "noteType.client",
- "value": "Client note"
- },
- "note": "First note\r\n\r\nedited",
- "createdById": 1,
- "createdByUsername": "mifos",
- "createdOn": 1342498505000,
- "updatedById": 1,
- "updatedByUsername": "mifos",
- "updatedOn": 1342498517000
- }
-]
-
-
-
+
+
-
- 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"
-}
-
-{
- "officeId": 1,
- "clientId": 1,
- "resourceId": 76
-}
-
-
+
-
-
+
-
+ 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.
- -
-
-
-
-
-
-
- Retrieve a Client Note
-Example Requests:
-clients/1/notes/76
- -
clients/1/notes/76?fields=note,createdOn,createdByUsername
-
-
-GET https://Domain Name/api/v1/clients/{clientId}/notes/{noteId}
- {
- "id": 76,
- "clientId": 1,
- "noteType": {
- "id": 100,
- "code": "noteType.client",
- "value": "Client note"
- },
- "note": "a note about the client",
- "createdById": 1,
- "createdByUsername": "mifos",
- "createdOn": 1359463135000,
- "updatedById": 1,
- "updatedByUsername": "mifos",
- "updatedOn": 1359463135000
-}
-
-
-
+
-
- Update a Client Note
-
-
-PUT https://Domain Name/api/v1/clients/{clientId}/notes/{noteId}
-PUT clients/1/notes/76
-Content-Type: application/json
-Request Body:
-{
-"note": "and here the note is updated nicely."
-}
-
-{
- "officeId": 1,
- "clientId": 1,
- "resourceId": 76,
- "changes": {
- "note": "and here the note is updated nicely."
- }
-}
-
- When you want to 'Update a ...' you can update individual + fields or a combination of fields (subject to data integrity + rules).
+
-
-
-
-
-
-
-
-
- Loans
-Field Descriptions |
| principal |
| The amount to be provided in the loan. |
| 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=repaymentSchedule,transactions
-
-
-GET https://Domain Name/api/v1/loans/{loanId}
- {
- "id": 1,
- "accountNo": "000000001",
- "clientId": 1,
- "clientName": "Petra Yton",
- "loanProductId": 1,
- "loanProductName": "A new loan product for me",
- "status": {
- "id": 100,
- "code": "loanStatusType.submitted.and.pending.approval",
- "value": "Submitted and pending approval"
- },
- "currency": {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- },
- "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
-}
+
+
+
+ Updating Dates and Numbers
+ Dates
+
+ Dates are returned in GET requests as an array e.g. [ 2007, 4,
+ 11]. However, the API accepts them as strings in POST and PUT
+ requests. If there are any dates in your POST or PUT requests, you
+ need to provide the "locale" and "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: { "locale": "en_US", "dateFormat": "dd
+ MMMM yyyy", "openingDate": "01 July 2007" } { "locale": "en_US",
+ "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" }
+
-
- {
- "officeId": 1,
- "clientId": 1,
- "loanId": 1,
- "resourceId": 1
-}
-
-
-
-
-
-
-
-
-
-
- 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:
-{
- "locale": "en",
- "dateFormat": "dd MMMM yyyy",
- "eventDate": "20 September 2011",
- "note": "and event note is added"
-}
-
- {
- "officeId": 1,
- "clientId": 1,
- "loanId": 2,
- "resourceId": 2,
- "changes": {
- "status": {
- "id": 200,
- "code": "loanStatusType.approved",
- "value": "Approved"
- },
- "locale": "en",
- "dateFormat": "dd MMMM yyyy",
- "approvedOnDate": "20 September 2011",
- "note": "and event note is added"
- }
-}
-
-
-
+
-
- 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:
-
- {
- "officeId": 1,
- "clientId": 1,
- "loanId": 1,
- "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"
- {
- "type": {
- "id": 2,
- "code": "loanTransactionType.repayment",
- "value": "Repayment"
- },
- "date": [
- 2011,
- 10,
- 20
- ],
- "currency": {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- },
- "amount": 9455.96
-}
-
-
-
+
+
-
- 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/1/transactions?command=repayment
-Content-Type: application/json
-Request Body:
-{
- "locale": "en_GB",
- "dateFormat": "dd MMMM yyyy",
- "transactionDate": "20 October 2011",
- "transactionAmount": "9,455.96"
-}
-
- {
- "officeId": 1,
- "clientId": 1,
- "loanId": 1,
- "resourceId": 2,
- "changes": {
- "transactionDate": "20 October 2011",
- "transactionAmount": "9,455.96",
- "locale": "en_GB",
- "dateFormat": "dd MMMM yyyy"
- }
-}
-
-
+
-
-
+
-
- Field Descriptions
++ Most fields are self-explanatory. Fields that aren't are described + under the relevant resource heading e.g. AUTHENTICATION +
- -
-
-
-
-
- Retrieve a Repayment or Waiver Details
-Example Request:
-loans/1/transactions/1
-
-
- GET https://Domain Name/api/v1/loans/{loanId}/transactions/{transactionId}
- {
- "id": 1,
- "type": {
- "id": 1,
- "code": "loanTransactionType.disbursement",
- "value": "Dibursement"
- },
- "date": [
- 2011,
- 9,
- 20
- ],
- "currency": {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- },
- "amount": 100000,
- "principalPortion": 0,
- "interestPortion": 0,
- "feeChargesPortion": 0,
- "penaltyChargesPortion": 0
-}
-
-
-
-
-
-
-
-
-
-
-
- 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/1/transactions/1
-Content-Type: application/json
-Request Body:
-{
- "locale": "en_GB",
- "dateFormat": "dd MMMM yyyy",
- "transactionDate": "20 October 2011",
- "transactionAmount": "9,455.00"
-}
-
- {
- "officeId": 1,
- "clientId": 1,
- "loanId": 1,
- "resourceId": 2,
- "changes": {
- "transactionDate": "20 October 2011",
- "transactionAmount": "9,455.00",
- "locale": "en_GB",
- "dateFormat": "dd MMMM yyyy"
- }
-}
-
-
-
-
-
-
-
-
-
- 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": "Head Office",
- "nameDecorated": "Head Office",
- "externalId": "1",
- "openingDate": [
- 2009,
- 1,
- 1
- ],
- "hierarchy": "."
- }
-]
-
-
-
+
-
- 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": [2013,2,4],
- "allowedParents": [
- {
- "id": 1,
- "name": "Head Office",
- "nameDecorated": "Head Office"
- }
- ]
-}
-
-
-
+
+
-
-
-
- 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": "Head Office",
- "nameDecorated": "Head Office",
- "externalId": "1",
- "openingDate": [2009,1,1],
- "hierarchy": "."
-}
-
-
+
-
-
+
+ Authentication Overview
++ Authentication to the API occurs via HTTP + Basic Auth. +
- -
-
+
-
-
-
- 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",
- "locale": "en",
- "openingDate": "01 July 2007",
- "parentId": 2,
- "externalId": "SYS54-88"
-}
-
-{
- "officeId": 3,
- "resourceId": 3
-}
-
- + 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 }); }
+
-
-
+
+
-
- Update Office
-
-
- PUT https://Domain Name/api/v1/offices/{officeId}
-PUT offices/1
-Content-Type: application/json
-Request Body:
-{
- "name": "Name is updated"
-}
-
-{
- "officeId": 1,
- "resourceId": 1,
- "changes": {
- "name": "Name is updated"
-}
-
-
+
+
+
+
-
-
-
+
+
+
+
+
+ Errors
- - - - -
-
-
-
-
-
-
-
- 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 |
| accountingType |
| - Example Values:NONE(1), CASH_BASED(2), ACCRUAL_BASED(3) |
-
-
-
-
-
-
- List Loan Products
-Example Requests:
-loanproducts
- -
loanproducts?fields=name,description,interestRateFrequencyType,amortizationType
-
-
- GET https://Domain Name/api/v1/loanproducts
- [
- {
- "id": 1,
- "name": "A new loan product for me",
- "currency": {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- },
- "principal": 100000,
- "numberOfRepayments": 12,
- "loanTermFrequency": 12,
- "repaymentEvery": 1,
- "loanTermFrequencyType": {
- "id": 2,
- "code": "loanTermFrequency.periodFrequencyType.months",
- "value": "Months"
- },
- "repaymentFrequencyType": {
- "id": 2,
- "code": "repaymentFrequency.periodFrequencyType.months",
- "value": "Months"
- },
- "transactionProcessingStrategyId": 1,
- "transactionProcessingStrategyName": "Mifos style",
- "interestRatePerPeriod": 1.75,
- "interestRateFrequencyType": {
- "id": 2,
- "code": "interestRateFrequency.periodFrequencyType.months",
- "value": "Per month"
- },
- "annualInterestRate": 21,
- "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"
- },
- "accountingType": 1
- }
-]
-
-
-
-
-
-
-
- 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
-{
- "currency": {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- },
- "loanTermFrequencyType": {
- "id": 2,
- "code": "loanTermFrequency.periodFrequencyType.months",
- "value": "Months"
- },
- "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"
- },
- "accountingType": 1,
- "currencyOptions": [
- {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- }
- ],
- "transactionProcessingStrategyOptions": [
- {
- "id": 1,
- "code": "mifos-standard-strategy",
- "name": "Mifos style"
- },
- {
- "id": 2,
- "code": "heavensfamily-strategy",
- "name": "Heavensfamily"
- },
- {
- "id": 3,
- "code": "creocore-strategy",
- "name": "Creocore"
- },
- {
- "id": 4,
- "code": "rbi-india-strategy",
- "name": "RBI (India)"
- }
- ],
- "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"
- }
- ],
- "loanTermFrequencyTypeOptions": [
- {
- "id": 0,
- "code": "loanTermFrequency.periodFrequencyType.days",
- "value": "Days"
- },
- {
- "id": 1,
- "code": "loanTermFrequency.periodFrequencyType.weeks",
- "value": "Weeks"
- },
- {
- "id": 2,
- "code": "loanTermFrequency.periodFrequencyType.months",
- "value": "Months"
- },
- {
- "id": 3,
- "code": "loanTermFrequency.periodFrequencyType.years",
- "value": "Years"
- }
- ],
- "accountingMappings": {}
-}
-
-
-
-
-
-
-
-
-
- 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": "A new loan product for me",
- "currency": {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- },
- "principal": 100000,
- "numberOfRepayments": 12,
- "loanTermFrequency": 12,
- "repaymentEvery": 1,
- "loanTermFrequencyType": {
- "id": 2,
- "code": "loanTermFrequency.periodFrequencyType.months",
- "value": "Months"
- },
- "repaymentFrequencyType": {
- "id": 2,
- "code": "repaymentFrequency.periodFrequencyType.months",
- "value": "Months"
- },
- "transactionProcessingStrategyId": 1,
- "transactionProcessingStrategyName": "Mifos style",
- "interestRatePerPeriod": 1.75,
- "interestRateFrequencyType": {
- "id": 2,
- "code": "interestRateFrequency.periodFrequencyType.months",
- "value": "Per month"
- },
- "annualInterestRate": 21,
- "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"
- },
- "accountingType": 1,
- "charges": []
-}
-
-
-
-
-
-
-
-
-
- Create a Loan Product
-Mandatory Fields |
| name, currencyCode, digitsAfterDecimal, principal, inArrearsTolerance, repaymentFrequencyType, repaymentEvery, - numberOfRepayments, interestRatePerPeriod, interestRateFrequencyType, amortizationType, - interestType, interestCalculationPeriodType, accountingType |
-
- POST https://Domain Name/api/v1/loanproducts
-POST loanproducts
-Content-Type: application/json
-Request Body:
-{
- "name": "A new loan product for me",
- "currencyCode": "USD",
- "locale": "en_GB",
- "digitsAfterDecimal": "2",
- "principal": "100,000.00",
- "numberOfRepayments": "12",
- "repaymentEvery": "1",
- "repaymentFrequencyType": 2,
- "transactionProcessingStrategyId": 1,
- "interestRatePerPeriod": "1.75",
- "interestRateFrequencyType": 2,
- "amortizationType": 1,
- "interestType": 0,
- "interestCalculationPeriodType": 1,
- "accountingType": 1
-}
-
-{
- "resourceId": 1
-}
-
-
-
-
-
-
-
-
-
- Update a Loan Product
-
-
- PUT https://Domain Name/api/v1/loanproducts/{loanId}
-PUT loanproducts/1
-Content-Type: application/json
-Request Body:
-{
- "locale": "en_GB",
- "principal": "70,000.00"
-}
-
-{
- "resourceId": 1,
- "changes": {
- "principal": 70000,
- "locale": "en_GB"
- }
-}
-
-
-
+
+
+
+
-
+ Currency
-Application related configuration around viewing/updating the currencies permitted for use within the MFI.
+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 |
+
| accountNo | +
| If provided during client creation, its + value is set as account no. for client account, otherwise an + auto generated account no. is put in place based on the + configured strategy. | +
| firstname | +
| Facility to break up name into parts + suitable for humans. | +
| middlename | +
| Facility to break up name into parts + suitable for humans. | +
| lastname | +
| Facility to break up name into parts + suitable for humans. | +
| fullname | +
| Facility to set name of a client or + business that doesnt suit the firstname,middlename,lastname + structure. | +
| 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
+ [ { "id": 2, "accountNo":
+ "000000002", "externalId": "one/78", "fullname": "New Business to
+ Create", "displayName": "New Business to Create", "officeId": 1,
+ "officeName": "Head Office", "joinedDate": [ 2006, 6, 13 ] }, {
+ "id": 1, "accountNo": "000000001", "externalId": "786YYH7",
+ "firstname": "Petra", "lastname": "Yton", "displayName": "Petra
+ Yton", "officeId": 1, "officeName": "Head Office", "joinedDate": [
+ 2009, 3, 4 ] } ]
+
+
+
+
+
+
+
+ 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
+ { "officeId": 1, "joinedDate":
+ [ 2013, 2, 5], "allowedOffices": [ { "id": 1, "name": "Head
+ Office", "nameDecorated": "Head Office" } ] }
+
+
+
+
+
+
+
+
+
+
+ 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}
+ { "id": 1, "accountNo":
+ "000000001", "externalId": "786YYH7", "firstname": "Petra",
+ "lastname": "Yton", "displayName": "Petra Yton", "officeId": 1,
+ "officeName": "Head Office", "joinedDate": [ 2009, 3, 4 ] }
+
+
+
+
+
+
+
+
+ Create a Client
+
+ Note: You can enter either:
+ firstname/middlename/lastname - for a person (middlename is
+ optional) OR
fullname - for a business or organisation
+ (or person known by one name).
+
Mandatory Fields |
+
| firstname and lastname OR fullname , 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" }
+ { "officeId": 1, "clientId":
+ 1, "resourceId": 1 }
+
+
+ POST clients Content-Type:
+ application/json Request Body: { "officeId": 1, "fullname": "New
+ Business to Create", "externalId": "one/78", "dateFormat": "dd
+ MMMM yyyy", "locale": "en", "joinedDate": "13 June 2006" }
+ { "officeId": 1, "clientId":
+ 2, "resourceId": 2 }
+
+
+
+
+
+
+ Update a Client
+
+
+ PUT https://Domain
+ Name/api/v1/clients/{clientId}
+ PUT clients/1 Content-Type:
+ application/json Request Body: { "externalId": "786444UUUYYH7",
+ "dateFormat": "dd MMMM yyyy", "locale": "en", "joinedDate": "09
+ June 2006" }
+ { "officeId": 1, "clientId":
+ 1, "resourceId": 1, "changes": { "externalId": "786444UUUYYH7",
+ "joinedDate": "09 June 2006", "dateFormat": "dd MMMM yyyy",
+ "locale": "en" } }
+
+
+
+
+
+
+
+
+ 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": 9,
+ "pendingApprovalLoanCount": 4, "pendingApprovalLoans": [ { "id":
+ 48, "accountNo": "48", "productId": 1, "productName":
+ "PORetailLoan", "status": { "id": 100, "code":
+ "loanStatusType.submitted.and.pending.approval", "value":
+ "Submitted and pending approval" } }, { "id": 50, "accountNo":
+ "50", "productId": 1, "productName": "PORetailLoan", "status": {
+ "id": 100, "code":
+ "loanStatusType.submitted.and.pending.approval", "value":
+ "Submitted and pending approval" } }, { "id": 51, "accountNo":
+ "51", "productId": 1, "productName": "PORetailLoan", "status": {
+ "id": 100, "code":
+ "loanStatusType.submitted.and.pending.approval", "value":
+ "Submitted and pending approval" } }, { "id": 62, "accountNo":
+ "62", "productId": 3, "productName": "Further Loan Product",
+ "status": { "id": 100, "code":
+ "loanStatusType.submitted.and.pending.approval", "value":
+ "Submitted and pending approval" } } ], "activeLoanCount": 2,
+ "openLoans": [ { "id": 46, "accountNo": "46", "productId": 1,
+ "productName": "PORetailLoan", "status": { "id": 300, "code":
+ "loanStatusType.active", "value": "Active" } }, { "id": 60,
+ "accountNo": "60", "productId": 1, "productName": "PORetailLoan",
+ "status": { "id": 300, "code": "loanStatusType.active", "value":
+ "Active" } } ], "closedLoanCount": 3, "closedLoans": [ { "id": 22,
+ "accountNo": "22", "productId": 1, "productName": "PORetailLoan",
+ "status": { "id": 700, "code": "loanStatusType.overpaid", "value":
+ "Overpaid" } }, { "id": 33, "accountNo": "33", "productId": 1,
+ "productName": "PORetailLoan", "status": { "id": 601, "code":
+ "loanStatusType.closed.written.off", "value": "Closed (written
+ off)" } }, { "id": 44, "accountNo": "44", "productId": 1,
+ "productName": "PORetailLoan", "status": { "id": 600, "code":
+ "loanStatusType.closed.obligations.met", "value": "Closed
+ (obligations met)" } } ] }
+
+
+
+
+
+
+
+
+ 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": 2, "clientId": 1,
+ "noteType": { "id": 100, "code": "noteType.client", "value":
+ "Client note" }, "note": "First note\r\n\r\nedited",
+ "createdById": 1, "createdByUsername": "mifos", "createdOn":
+ 1342498505000, "updatedById": 1, "updatedByUsername": "mifos",
+ "updatedOn": 1342498517000 } ]
+
+
+
+
+
+
+ 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" }
+ { "officeId": 1, "clientId":
+ 1, "resourceId": 76 }
+
+
+
+
+
+
+
+
+ Retrieve a Client Note
+Example Requests:
+clients/1/notes/76
+ +
+
clients/1/notes/76?fields=note,createdOn,createdByUsername
+
+
+ GET https://Domain
+ Name/api/v1/clients/{clientId}/notes/{noteId}
+ { "id": 76, "clientId": 1,
+ "noteType": { "id": 100, "code": "noteType.client", "value":
+ "Client note" }, "note": "a note about the client", "createdById":
+ 1, "createdByUsername": "mifos", "createdOn": 1359463135000,
+ "updatedById": 1, "updatedByUsername": "mifos", "updatedOn":
+ 1359463135000 }
+
+
+
+
+
+
+
+
+ Update a Client Note
+
+
+ PUT https://Domain
+ Name/api/v1/clients/{clientId}/notes/{noteId}
+ PUT clients/1/notes/76
+ Content-Type: application/json Request Body: { "note": "and here
+ the note is updated nicely." }
+ { "officeId": 1, "clientId":
+ 1, "resourceId": 76, "changes": { "note": "and here the note is
+ updated nicely." } }
+
+
+
+
+
+
+
+
+
+ Loans
+Field Descriptions |
+
| principal | +
| The amount to be provided in the loan. | +
| 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=repaymentSchedule,transactions
+
+
+ GET https://Domain
+ Name/api/v1/loans/{loanId}
+ { "id": 1, "accountNo":
+ "000000001", "clientId": 1, "clientName": "Petra Yton",
+ "loanProductId": 1, "loanProductName": "A new loan product for
+ me", "status": { "id": 100, "code":
+ "loanStatusType.submitted.and.pending.approval", "value":
+ "Submitted and pending approval" }, "currency": { "code": "USD",
+ "name": "US Dollar", "decimalPlaces": 2, "displaySymbol": "$",
+ "nameCode": "currency.USD", "displayLabel": "US Dollar ($)" },
+ "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 }
+ { "officeId": 1, "clientId":
+ 1, "loanId": 1, "resourceId": 1 }
+
+
+
+
+
+
+
+
+ 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: { "locale": "en",
+ "dateFormat": "dd MMMM yyyy", "eventDate": "20 September 2011",
+ "note": "and event note is added" }
+ { "officeId": 1, "clientId":
+ 1, "loanId": 2, "resourceId": 2, "changes": { "status": { "id":
+ 200, "code": "loanStatusType.approved", "value": "Approved" },
+ "locale": "en", "dateFormat": "dd MMMM yyyy", "approvedOnDate":
+ "20 September 2011", "note": "and event note is added" } }
+
+
+
+
+
+
+ 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:
+ { "officeId": 1, "clientId":
+ 1, "loanId": 1, "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": "Head
+ Office", "nameDecorated": "Head Office", "externalId": "1",
+ "openingDate": [ 2009, 1, 1 ], "hierarchy": "." } ]
+
+
+
+
+
+
+ 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": [2013,2,4],
+ "allowedParents": [ { "id": 1, "name": "Head Office",
+ "nameDecorated": "Head Office" } ] }
+
+
+
+
+
+
+
+
+
+
+ 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": "Head
+ Office", "nameDecorated": "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", "locale": "en", "openingDate": "01
+ July 2007", "parentId": 2, "externalId": "SYS54-88" }
+ { "officeId": 3, "resourceId":
+ 3 }
+
+
+
+
+
+
+
+
+
+
+ Update Office
+
+
+ PUT https://Domain
+ Name/api/v1/offices/{officeId}
+ PUT offices/1 Content-Type:
+ application/json Request Body: { "name": "Name is updated" }
+ { "officeId": 1, "resourceId":
+ 1, "changes": { "name": "Name is updated" }
+
+
+
+
+
+
+
+
+ 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 | +
| accountingType | +
| Example Values:NONE(1), + CASH_BASED(2), ACCRUAL_BASED(3) | +
+
+
+
+
+
+
+
+ List Loan Products
+Example Requests:
+loanproducts
+ +
+
loanproducts?fields=name,description,interestRateFrequencyType,amortizationType
+
+
+ GET https://Domain
+ Name/api/v1/loanproducts
+ [ { "id": 1, "name": "A new
+ loan product for me", "currency": { "code": "USD", "name": "US
+ Dollar", "decimalPlaces": 2, "displaySymbol": "$", "nameCode":
+ "currency.USD", "displayLabel": "US Dollar ($)" }, "principal":
+ 100000, "numberOfRepayments": 12, "loanTermFrequency": 12,
+ "repaymentEvery": 1, "loanTermFrequencyType": { "id": 2, "code":
+ "loanTermFrequency.periodFrequencyType.months", "value": "Months"
+ }, "repaymentFrequencyType": { "id": 2, "code":
+ "repaymentFrequency.periodFrequencyType.months", "value": "Months"
+ }, "transactionProcessingStrategyId": 1,
+ "transactionProcessingStrategyName": "Mifos style",
+ "interestRatePerPeriod": 1.75, "interestRateFrequencyType": {
+ "id": 2, "code":
+ "interestRateFrequency.periodFrequencyType.months", "value": "Per
+ month" }, "annualInterestRate": 21, "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" }, "accountingType": 1 } ]
+
+
+
+
+
+
+ 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
+ { "currency": { "code": "USD",
+ "name": "US Dollar", "decimalPlaces": 2, "displaySymbol": "$",
+ "nameCode": "currency.USD", "displayLabel": "US Dollar ($)" },
+ "loanTermFrequencyType": { "id": 2, "code":
+ "loanTermFrequency.periodFrequencyType.months", "value": "Months"
+ }, "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" }, "accountingType": 1,
+ "currencyOptions": [ { "code": "USD", "name": "US Dollar",
+ "decimalPlaces": 2, "displaySymbol": "$", "nameCode":
+ "currency.USD", "displayLabel": "US Dollar ($)" } ],
+ "transactionProcessingStrategyOptions": [ { "id": 1, "code":
+ "mifos-standard-strategy", "name": "Mifos style" }, { "id": 2,
+ "code": "heavensfamily-strategy", "name": "Heavensfamily" }, {
+ "id": 3, "code": "creocore-strategy", "name": "Creocore" }, {
+ "id": 4, "code": "rbi-india-strategy", "name": "RBI (India)" } ],
+ "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" } ], "loanTermFrequencyTypeOptions": [ { "id": 0, "code":
+ "loanTermFrequency.periodFrequencyType.days", "value": "Days" }, {
+ "id": 1, "code": "loanTermFrequency.periodFrequencyType.weeks",
+ "value": "Weeks" }, { "id": 2, "code":
+ "loanTermFrequency.periodFrequencyType.months", "value": "Months"
+ }, { "id": 3, "code":
+ "loanTermFrequency.periodFrequencyType.years", "value": "Years" }
+ ], "accountingMappings": {} }
+
+
+
+
+
+
+
+
+
+
+ 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": "A new loan
+ product for me", "currency": { "code": "USD", "name": "US Dollar",
+ "decimalPlaces": 2, "displaySymbol": "$", "nameCode":
+ "currency.USD", "displayLabel": "US Dollar ($)" }, "principal":
+ 100000, "numberOfRepayments": 12, "loanTermFrequency": 12,
+ "repaymentEvery": 1, "loanTermFrequencyType": { "id": 2, "code":
+ "loanTermFrequency.periodFrequencyType.months", "value": "Months"
+ }, "repaymentFrequencyType": { "id": 2, "code":
+ "repaymentFrequency.periodFrequencyType.months", "value": "Months"
+ }, "transactionProcessingStrategyId": 1,
+ "transactionProcessingStrategyName": "Mifos style",
+ "interestRatePerPeriod": 1.75, "interestRateFrequencyType": {
+ "id": 2, "code":
+ "interestRateFrequency.periodFrequencyType.months", "value": "Per
+ month" }, "annualInterestRate": 21, "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" }, "accountingType": 1, "charges": [] }
+
+
+
+
+
+
+
+
+
+ Create a Loan Product
+Mandatory Fields |
+
| name, currencyCode, digitsAfterDecimal, principal, + inArrearsTolerance, repaymentFrequencyType, repaymentEvery, + numberOfRepayments, interestRatePerPeriod, + interestRateFrequencyType, amortizationType, interestType, + interestCalculationPeriodType, accountingType | +
+
+ POST https://Domain
+ Name/api/v1/loanproducts
+ POST loanproducts Content-Type:
+ application/json Request Body: { "name": "A new loan product for
+ me", "currencyCode": "USD", "locale": "en_GB",
+ "digitsAfterDecimal": "2", "principal": "100,000.00",
+ "numberOfRepayments": "12", "repaymentEvery": "1",
+ "repaymentFrequencyType": 2, "transactionProcessingStrategyId": 1,
+ "interestRatePerPeriod": "1.75", "interestRateFrequencyType": 2,
+ "amortizationType": 1, "interestType": 0,
+ "interestCalculationPeriodType": 1, "accountingType": 1 }
+ { "resourceId": 1 }
+
+
+
+
+
+
+
+
+ Update a Loan Product
+
+
+ PUT https://Domain
+ Name/api/v1/loanproducts/{loanId}
+ PUT loanproducts/1
+ Content-Type: application/json Request Body: { "locale": "en_GB",
+ "principal": "70,000.00" }
+ { "resourceId": 1, "changes":
+ { "principal": 70000, "locale": "en_GB" } }
+
+
+
+
+
+
+ Currency
+Application related configuration around viewing/updating + 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:
+currencies
+ +
+
currencies?fields=selectedCurrencyOptions
+
+
+ GET https://Domain
+ Name/api/v1/currencies
+ { "selectedCurrencyOptions": [
+ { "code": "USD", "name": "US Dollar", "decimalPlaces": 2,
+ "displaySymbol": "$", "nameCode": "currency.USD", "displayLabel":
+ "US Dollar ($)" } ], "currencyOptions": [ { "code": "AFN", "name":
+ "Afghanistan Afghani", "decimalPlaces": 2, "nameCode":
+ "currency.AFN", "displayLabel": "Afghanistan Afghani [AFN]" }, {
+ "code": "ALL", "name": "Albanian Lek", "decimalPlaces": 2,
+ "nameCode": "currency.ALL", "displayLabel": "Albanian Lek [ALL]"
+ }, { "code": "ZWD", "name": "Zimbabwe Dollar", "decimalPlaces": 2,
+ "nameCode": "currency.ZWD", "displayLabel": "Zimbabwe Dollar
+ [ZWD]" } ] }
+
+
+
+
+
+
+ Update Currency Configuration
+Updates the list of currencies permitted for use.
+
+
+ PUT https://Domain
+ Name/api/v1/currencies
+ PUT currencies Content-Type:
+ application/json Request Body: { "currencies": ["KES", "BND",
+ "LBP", "GHC", "USD", "XOF", "AED", "AMD"] }
+ { "currencies": [ "KES",
+ "BND", "LBP", "GHC", "USD", "XOF", "AED", "AMD" ] }
+
+
+
+
+
+
+ Global Configuration
+Global configuration related to set of supported + enable/disable configurations e.g. maker-checker.
+
+
+
+
+
+
+ Retrieve Global Configuration
+Returns the list global enable/disable configurations.
+Example Requests:
+configurations
+
+
+ GET https://Domain
+ Name/api/v1/configurations
+ { "globalConfiguration": [ {
+ "name": "maker-checker", "enabled": false } ] }
+
+
+
+
+
+
+ Update Global Configuration
+Updates an enable/disable global configuration item.
+
+
+ PUT https://Domain
+ Name/api/v1/configurations?maker-checker=false
+ PUT configurations
+ Content-Type: application/json Request Body: { }
+ { "changes": {} }
+
+
+
+
+
+
+ Codes
+Code and code values: Codes represent a specific category of + data, their code values are a specific instance of that category.
++ Codes are mostly system defined which means the code itself + comes out of the box and cannot be modifed however its code values + can be. e.g. 'Customer Identifier', it defaults to a code value of + 'Passport' but could be 'Drivers License, National Id' etc +
+
+
+
+
+
+
+ Create a Code
+Creates a code. Codes created through api are always 'user + defined' and so system defined is marked as false.
+
+
+ POST https://Domain
+ Name/api/v1/codes
+ POST codes Content-Type:
+ application/json Request Body: { "name": "MyNewCode" }
+ { "resourceId": 4 }
+
+
+
+
+
+
+ Retrieve Codes
+Returns the list of codes.
+Example Requests:
+codes
+
+
+ GET https://Domain
+ Name/api/v1/codes
+ [ { "id": 1, "name": "Customer
+ Identifier", "systemDefined": true }, { "id": 2, "name": "Gender",
+ "systemDefined": true },{ "id": 3, "name": "Education",
+ "systemDefined": true } ]
+
+
+
+
+
+
+ Retrieve a Code
+Returns the details of a Code.
+Example Requests:
+codes/1
+
+
+ GET https://Domain
+ Name/api/v1/codes/1
+ { "id": 1, "name": "Customer
+ Identifier", "systemDefined": true }
+
+
+
+
+
+
+ Update a Code
+Updates the details of a code if it is not system defined.
+
+
+ PUT https://Domain
+ Name/api/v1/codes/4
+ PUT codes/4 Content-Type:
+ application/json Request Body: { "name": "MyNewCode(changed)" }
+ { "resourceId": 4, "changes":
+ { "name": "MyNewCode(changed)" } }
+
+
+
+
+
+
+ Delete a Code
+Deletes a code if it is not system defined.
+
+
+ DELETE https://Domain
+ Name/api/v1/codes/4
+ DELETE codes/4 Content-Type:
+ application/json
+ { "resourceId": 4 }
+
+
+
+
+
+
+ Funds
+Simple implementation of funds. At present funds can + optionally be associated with a Loan.
+This information can then be used to produce reports on + loans/loan amounts drawn from a fund.
+
+
+
+
+
+
+ Create a Fund
+Creates a fund.
+
+
+ POST https://Domain
+ Name/api/v1/funds
+ POST funds Content-Type:
+ application/json Request Body: { "name": "EU Agri Fund" }
+ { "resourceId": 1 }
+
+
+
+
+
+
+ Retrieve Funds
+Returns the list of funds.
+Example Requests:
+funds
+
+
+ GET https://Domain
+ Name/api/v1/funds
+ [ { "id": 1, "name": "EU Agri
+ Fund" } ]
+
+
+
+
+
+
+ Retrieve a Fund
+Returns the details of a Fund.
+Example Requests:
+funds/1
+
+
+ GET https://Domain
+ Name/api/v1/funds/1
+ { "id": 1, "name": "EU Agri
+ Fund" }
+
+
+
+
+
+
+
+ Update a Fund
+Updates the details of a fund.
+
+
+ PUT https://Domain
+ Name/api/v1/funds/1
+ PUT funds/1 Content-Type:
+ application/json Request Body: { "name": "EU Agri Fund
+ (2010-2020)" }
+ { "resourceId": 1, "changes":
+ { "name": "EU Agri Fund (2010-2020)" } }
+
+
+
+
+
+
+ Staff
+Allows you to model staff members. At present the key role + of signifigance is whether this staff member is a loan officer or + not.
+
+
+
+
+
+
+ Create a staff member
+Creates a staff member.
+
+
+ POST https://Domain
+ Name/api/v1/staff
+ POST staff Content-Type:
+ application/json Request Body: { "officeId": 1, "firstname":
+ "John", "lastname": "Doe", "isLoanOfficer": "true" }
+ { "officeId": 1, "resourceId":
+ 1 }
+
+
+
+
+
+
+ Retrieve Staff
+Returns the list of staff members.
+Example Requests:
+staff
+
+
+ GET https://Domain
+ Name/api/v1/staff
+ [ { "id": 1, "firstname":
+ "John", "lastname": "Doe", "displayName": "Doe, John", "officeId":
+ 1, "officeName": "Head Office", "isLoanOfficer": true } ]
+
+
+
+
+
+
+ Retrieve a Staff Member
+Returns the details of a Staff Member.
+Example Requests:
+staff/1
+
+
+ GET https://Domain
+ Name/api/v1/staff/1
+ { "id": 1, "firstname":
+ "John", "lastname": "Doe", "displayName": "Doe, John", "officeId":
+ 1, "officeName": "Head Office", "isLoanOfficer": true }
+
+
+
+
+
+
+
+ Update a Staff Member
+Updates the details of a staff member.
+
+
+ PUT https://Domain
+ Name/api/v1/staff/1
+ PUT staff/1 Content-Type:
+ application/json Request Body: { "isLoanOfficer": "false" }
+ { "officeId": 1, "resourceId":
+ 1, "changes": { "isLoanOfficer": false } }
+
+
+
+
+
+
+ Charges
++ Its typical for MFIs to add extra costs to their financial + products. There are typically Fees or Penalites. +
+Charges is what we use to model both fees and penalities. + For now charges can only be associated with loan products / loans.
+
+
+
+
+
+
+ Create/Define a Charge
+Define a new charge that can later be associated with loan + products or loans.
+
+
+ POST https://Domain
+ Name/api/v1/charges
+ POST charges Content-Type:
+ application/json Request Body: { "name": "Loan service fee",
+ "chargeAppliesTo": 1, "currencyCode": "USD", "locale": "en",
+ "amount": "230.56", "chargeTimeType": "1",
+ "chargeCalculationType": "1" }
+ { "resourceId": 1 }
+
+
+
+
+
+
+ Retrieve Charges
+Returns the list of defined charges.
+Example Requests:
+charges
+
+
+ GET https://Domain
+ Name/api/v1/charges
+ [ { "id": 1, "name": "Loan
+ service fee", "active": true, "penalty": false, "currency": {
+ "code": "USD", "name": "US Dollar", "decimalPlaces": 2,
+ "displaySymbol": "$", "nameCode": "currency.USD", "displayLabel":
+ "US Dollar ($)" }, "amount": 230.560000, "chargeTimeType": { "id":
+ 1, "code": "chargeTimeType.disbursement", "value": "Disbursement"
+ }, "chargeAppliesTo": { "id": 1, "code": "chargeAppliesTo.loan",
+ "value": "Loan" }, "chargeCalculationType": { "id": 1, "code":
+ "chargeCalculationType.flat", "value": "Flat" } } ]
+
+
+
+
+
+
+ Retrieve a Charge
+Returns the details of a defined Charge.
+Example Requests:
+charges/1
+
+
+ GET https://Domain
+ Name/api/v1/charges/1
+ { "id": 1, "name": "Loan
+ service fee", "active": true, "penalty": false, "currency": {
+ "code": "USD", "name": "US Dollar", "decimalPlaces": 2,
+ "displaySymbol": "$", "nameCode": "currency.USD", "displayLabel":
+ "US Dollar ($)" }, "amount": 230.560000, "chargeTimeType": { "id":
+ 1, "code": "chargeTimeType.disbursement", "value": "Disbursement"
+ }, "chargeAppliesTo": { "id": 1, "code": "chargeAppliesTo.loan",
+ "value": "Loan" }, "chargeCalculationType": { "id": 1, "code":
+ "chargeCalculationType.flat", "value": "Flat" } }
+
+
+
+
+
+
+ Update a Charge
+Updates the details of a Charge.
+
+
+ PUT https://Domain
+ Name/api/v1/charges/1
+ PUT charges/1 Content-Type:
+ application/json Request Body: { "name": "Loan service
+ fee(changed)" }
+ { "resourceId": 1, "changes":
+ { "name": "Loan service fee(changed)" } }
+
+
+
+
+
+
+
+ Delete a Charge
+Deletes a Charge.
+
+
+ DELETE https://Domain
+ Name/api/v1/charges/1
+ DELETE charges/1 Content-Type:
+ application/json
+ { "resourceId": 1 }
+
+
+
+
+
+
+
+ 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¶meterType=true
+ +
+
reports/selectOfficeId?R_officeId=1¶meterType=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=mifos&password=password Content-Type:
+ application/json No Request Body
+ { "username": "mifos",
+ "userId": 1, "base64EncodedAuthenticationKey":
+ "bWlmb3M6cGFzc3dvcmQ=", "authenticated": true, "permissions": [
+ "ALL_FUNCTIONS" ] }
+
+ POST
+ authentication?username=mifos&password=fail Content-Type:
+ application/json No Request Body
+ { "developerMessage": "Invalid
+ authentication details were passed in api request.",
+ "developerDocLink":
+ "https://github.com/keithwoodlock/mifosx/wiki/HTTP-API-Error-codes",
+ "httpStatusCode": "401", "defaultUserMessage": "Unauthenticated.
+ Please login.", "userMessageGlobalisationCode":
+ "error.msg.not.authenticated", "errors": [] }
+
+
+
+
+
+
+ Users
+An API capability to support administration of application + users.
+
+
+
+
+
+
+
+
+ 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." },... ] }
+
+
+
+
+
+
+
+
+
+
+
+ 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", "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 at present 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] }
+ { "officeId": 1,
+ "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", "password":
+ "window75", "repeatPassword": "window75" }
+ { "officeId": 1,
+ "resourceId": 3, "changes": { "firstname": "Test",
+ "passwordEncoded":
+ "abc3326b1bb376351c7baeb4175f5e0504e33aadf6a158474a6d71de1befae51"
+ } }
+
+
+
+
+
+
+
+
+
+ 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
+ { "officeId": 1, "resourceId":
+ 20, "changes": {} }
+
+
+
+
+
+
+ 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: { "description": "some
+ description(changed)" }
+ { "resourceId": 8, "changes":
+ { "description": "some description(changed)" } }
+
+
+
+
+
+
+ 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 }, {
+ "grouping": "authorisation", "code": "CREATE_ROLE", "entityName":
+ "ROLE", "actionName": "CREATE", "selected": false, }, {
+ "grouping": "authorisation", "code": "DELETE_ROLE", "entityName":
+ "ROLE", "actionName": "DELETE", "selected": false },...] }
+
+
+
+
+
+
+
+ Update a Role's Permissions
+
+
+ PUT https://Domain
+ Name/api/v1/roles/{roleId}/permissions
+ PUT roles/8 Content-Type:
+ application/json Request body: { "permissions":
+ {"ALL_FUNCTIONS_READ": "true"} }
+ { "resourceId": 8, "changes":
+ { "permissions": { "ALL_FUNCTIONS_READ": true } } }
+
+
+
+
+
+
+ Permissions
+An API capability to support management of application + permissions for user administration.
+
+
+
+>>>>>>> update api docs format
+
+
+
+
+ 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 }, {
+ "grouping": "authorisation", "code": "CREATE_ROLE", "entityName":
+ "ROLE", "actionName": "CREATE", "selected": true }, { "grouping":
+ "authorisation", "code": "DELETE_ROLE", "entityName": "ROLE",
+ "actionName": "DELETE", "selected": true }, ... ]
+ +
+
+
+
+
+
+
+
+ Full API Matrix + |
+
+
+
|
+
|
+ |||
| clients/template | +Retrieve Client Details + Template | +|||
| loans/template | +Retrieve Loan Details + Template | +|||
| loans/{loanId}/transactions/template | +Retrieve Loan + Repayment/Loan Waiver Template | +|||
| offices/template | +Retrieve Office Details + Template | +|||
| loanproducts/template | +Retrieve Loan Product + Details Template | +|||
| users/template | +Retrieve User Details + Template | +|||
| audit/searchtemplate | +Retrieve Audit Search + Data | +
-
-
-
-
-
-
- Retrieve Currency Configuration
-Returns the list of currencies permitted for use AND the list of currencies not selected (but available for selection).
-Example Requests:
-currencies
- -
currencies?fields=selectedCurrencyOptions
-
-
- GET https://Domain Name/api/v1/currencies
- {
- "selectedCurrencyOptions": [
- {
- "code": "USD",
- "name": "US Dollar",
- "decimalPlaces": 2,
- "displaySymbol": "$",
- "nameCode": "currency.USD",
- "displayLabel": "US Dollar ($)"
- }
- ],
- "currencyOptions": [
- {
- "code": "AFN",
- "name": "Afghanistan Afghani",
- "decimalPlaces": 2,
- "nameCode": "currency.AFN",
- "displayLabel": "Afghanistan Afghani [AFN]"
- },
- {
- "code": "ALL",
- "name": "Albanian Lek",
- "decimalPlaces": 2,
- "nameCode": "currency.ALL",
- "displayLabel": "Albanian Lek [ALL]"
- },
- {
- "code": "ZWD",
- "name": "Zimbabwe Dollar",
- "decimalPlaces": 2,
- "nameCode": "currency.ZWD",
- "displayLabel": "Zimbabwe Dollar [ZWD]"
- }
- ]
-}
-
-
-
+
+ });
+
-
- Update Currency Configuration
-Updates the list of currencies permitted for use.
-
-
- PUT https://Domain Name/api/v1/currencies
- PUT currencies
-Content-Type: application/json
-Request Body:
-{
-"currencies": ["KES", "BND", "LBP", "GHC", "USD", "XOF", "AED", "AMD"]
-}
-
- {
- "currencies": [
- "KES",
- "BND",
- "LBP",
- "GHC",
- "USD",
- "XOF",
- "AED",
- "AMD"
- ]
-}
-
-