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 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.
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.
// Typically, the javascript application would
// 1) Display a login page to retrieve the username and password.
// 2) Send the username and password to a function
// such as setBasicAuthKey below which sets the HTTP Basic Auth key.
// 3) The HTTP Basic Auth key is used in all subsequent requests
// (see the function executeAjaxRequest below).
function setBasicAuthKey(username, password) {
var jqxhr = $.ajax({
url : "authentication?username=" + username + "&password=" + password,
type : 'POST',
contentType : "application/json; charset=utf-8",
dataType : 'json',
data : "{}",
cache : false,
success : function(data, textStatus, jqXHR) {
basicAuthKey = data.base64EncodedAuthenticationKey;
},
error : function(jqXHR, textStatus, errorThrown) {
//error processing
}
});
}
function executeAjaxRequest(url, verbType, jsonData, basicAuthKey, successFunction, errorFunction) {
var jqxhr = $.ajax({
url : url,
type : verbType, //POST, GET, PUT or DELETE
contentType : "application/json; charset=utf-8",
dataType : 'json',
data : jsonData,
cache : false,
beforeSend : function(xhr) {
xhr.setRequestHeader("Authorization", "Basic " + basicAuthKey);
},
success : successFunction,
error : errorFunction
});
}
Errors
All errors are returned in JSON.
HTTP Status Code Summary
- 200 OK - Everything Worked.
- 400 Bad Request - Invalid Parameter or Data Integrity Issue.
- 401 Authentication Error.
- 403 Unauthorized Request.
- 404 Resource Not Found
- 500 Platform Internal Server Error.
Error Message returned when attempting to create an Office without passing any parameters
{
"developerMessage": "The request was invalid. This typically will happen due to validation errors which are provided.",
"developerDocLink": "https://github.com/openMF/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.
Clients can be created in Pending or straight into Active state.
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. |
| externalId |
| A place to put an external reference for
this client e.g. The ID another system uses. If provided, it must be unique. |
| active |
| Indicates whether this client is to be created as active client. If active=true, then activationDate must be provided. If active=false, then the client is created as pending. |
| activationDate |
| The date on which the client became active. |
| 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. |
| mobileNo |
| Optional: unique mobile number that is used by SMS or Mobile Money functionality. |
| staffId |
| The staffId of the staff member dealing with the client office. The staff member is not specifically the loan officer. |
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
Arguments
- officeId
- Integer optional
- staffInSelectedOfficeOnly
- Boolean optional
- Defaults to false if not provided. If staffInSelectedOfficeOnly=true only staff who are associated with the selected branch are returned.
- commandParam
- String optional
- If commandParam=close retrieves all closureReasons which are associated with "ClientClosureReason" value.
Example Request:
clients/template
GET https://DomainName/api/v1/clients/template
{
"activationDate": [
2013,
4,
17
],
"officeId": 1,
"officeOptions": [
{
"id": 1,
"name": "Head Office",
"nameDecorated": "Head Office"
}
]
}
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, officeId, active=true and activationDate OR active=false, |
Optional Fields |
| groupId, externalId, accountNo, staffId, mobileNo |
POST https://DomainName/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",
"active": true,
"activationDate": "04 March 2009",
"submittedOnDate":"04 March 2009"
}
{
"officeId": 1,
"clientId": 1,
"resourceId": 1
}
POST clients
Content-Type: application/json
Request Body:
{
"officeId": 1,
"fullname": "Client of group",
"groupId": 1,
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"active": true,
"activationDate": "04 March 2009"
}
{
"officeId": 1,
"groupId": 1,
"clientId": 2,
"resourceId": 2
}
Activate a Client
Clients can be created in a Pending state. This API exists to enable client activation (for when a client becomes approved member of microfinance institue).
If the client happens to be alrady active this API will result in an error.
POST https://Domain Name/api/v1/clients/{clientId}?command=activate
POST clients/1?command=activate
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"activationDate": "01 March 2011"
}
{
"officeId": 1,
"clientId": 1,
"resourceId": 1
}
Close a Client
Clients can be closed if they dont have any non-closed loans/savingsAccount. This API exists to close a client .
If the client have any corresponding active loans/savingsAccount this API will result in an error.
POST https://Domain Name/api/v1/clients/{clientId}?command=close
POST clients/1?command=close
Content-Type: application/json
Request Body:
{
"dateFormat":"dd MMMM yyyy",
"locale":"en",
"closureDate":"25 June 2013",
"closureReasonId":"11"
}
{
"clientId":15,
"resourceId":15
}
Assign a Staff
Allows you to assign Staff for existed Client.
The selected Staff member should be belongs to the client's office.
POST https://Domain Name/api/v1/clients/{clientId}?command=assignStaff
POST clients/1?command=assignStaff
Content-Type: application/json
Request Body:
{
"staffId": "1"
}
{
"officeId": 1,
"clientId": 1,
"resourceId": 1,
"changes": {"staffId":1}
}
Unassign a Staff
Allows you to unassign the Staff.
POST https://Domain Name/api/v1/clients/{clientId}?command=unassignStaff
POST clients/1?command=unassignStaff
Content-Type: application/json
Request Body:
{
"staffId":"1"
}
{
"officeId": 1,
"clientId": 1,
"resourceId": 1,
"changes": {"staffId":1}
}
Propose a Client Transfer
Allows you to propose the transfer of a Client to a different Offices.
POST https://Domain Name/api/v1/clients/{clientId}?command=proposeTransfer
POST clients/1?command=proposeTransfer
Content-Type: application/json
Request Body:
{
"destinationOfficeId":"2",
"note":"Client Relocating to Bangalore"
}
{
"clientId": 2,
"resourceId": 2
}
Withdraw a Client Transfer
Allows you to withdraw the proposed the transfer of a Client to a different Offices.
Withdrawal can happen only if the destination Branch (to which the transfer was proposed) has not already accepted the transfer proposal
POST https://Domain Name/api/v1/clients/{clientId}?command=withdrawTransfer
POST clients/1?command=withdrawTransfer
Content-Type: application/json
Request Body:
{
"note":"Sorry, data entry error"
}
{
"clientId": 2,
"resourceId": 2
}
Reject a Client Transfer
Allows the Destination Branch to reject the proposed Client Transfer.
POST https://Domain Name/api/v1/clients/{clientId}?command=rejectTransfer
POST clients/1?command=rejectTransfer
Content-Type: application/json
Request Body:
{
"note":"We cannot accept tranfers of clients having loans with less than 1 repayment left"
}
{
"clientId": 2,
"resourceId": 2
}
Accept a Client Transfer
Allows the Destination Branch to accept the proposed Client Transfer.
The destination branch may also choose to link this client to a group (in which case, any existing active JLG loan of the client is rescheduled to match the meeting frequency of the group) and loan Officer at the time of accepting the transfer
POST https://Domain Name/api/v1/clients/{clientId}?command=acceptTransfer
POST clients/1?command=acceptTransfer
Content-Type: application/json
Request Body:
{
"destinationGroupId":"13",
"staffId":"1",
"note":"Due Diligence done and all documents received"
}
{
"clientId": 2,
"resourceId": 2
}
Propose and Accept a Client Transfer
Abstraction over the Propose and Accept Client Transfer API's which enable a user with Data Scope over both the Target and Destination Branches to directly transfer a Client to the destination Office.
POST https://Domain Name/api/v1/clients/{clientId}?command=proposeAndAcceptTransfer
POST clients/1?command=proposeTransfer
Content-Type: application/json
Request Body:
{
"destinationOfficeId":"2",
"destinationGroupId":"13",
"staffId":"1",
"note":"Client Relocating to Bangalore"
}
{
"clientId": 2,
"resourceId": 2
}
Retrieve a Client
Example Requests:
clients/1
clients/1?template=true
clients/1?fields=id,displayName,officeName
GET https://DomainName/api/v1/clients/{clientId}
{
"id": 2,
"accountNo": "000000002",
"status": {
"id": 300,
"code": "clientStatusType.active",
"value": "Active"
},
"activationDate": [
2009,
3,
4
],
"fullname": "Client of group",
"displayName": "Client of group",
"officeId": 1,
"officeName": "Head Office",
"timeline": {
"activatedOnDate": [
2009,
3,
4
],
"activatedByUsername": "mifos",
"activatedByFirstname": "App",
"activatedByLastname": "Administrator"
},
"groups": [
{
"id": 1,
"name": "Example Group"
}
]
}
List Clients
The list capability of clients can support pagination and sorting.
Optional Arguments
- offset
- Integer optional, defaults to 0
- Indicates from what result to start from.
- limit
- Integer optional, defaults to 200
- Restricts the size of results returned. To override the default and return all entries you must explicitly pass a non-positive integer value for limit e.g. limit=0, or limit=-1
- orderBy
- String optional, one of displayName, accountNo, officeId, officeName
- Orders the results by the field indicated.
- sortBy
- String optional, one of ASC, DESC
- Indicates what way to order results if orderBy is used.
- officeId
- Integer optional
- Provides ability to restrict list of clients returned based on the office there associated with.
- underHierarchy
- String optional
- Use the office hierarchy string to return all clients under a given hierarchy.
- displayName
- String optional
- Use displayName of clients to restrict results.
- firstName
- String optional
- Use firstName of clients to restrict results.
- lastName
- String optional
- Use lastName of clients to restrict results.
- externalId
- String optional
- Use externalId of clients to restrict results.
- sqlSearch
- String optional
- Use an sql fragment valid for the underlying client schema to filter results. e.g. display_name like %K%
Example Requests:
clients
clients?fields=displayName,officeName,joinedDate
clients?offset=10&limit=50
clients?orderBy=displayName,sortOrder=DESC
GET https://DomainName/api/v1/clients
{
"totalFilteredRecords": 2,
"pageItems": [
{
"id": 1,
"accountNo": "000000001",
"status": {
"id": 300,
"code": "clientStatusType.active",
"value": "Active"
},
"active": true,
"activationDate": [
2013,
3,
1
],
"fullname": "Small shop",
"displayName": "Small shop",
"officeId": 1,
"officeName": "Head Office"
},
{
"id": 2,
"accountNo": "000000002",
"status": {
"id": 100,
"code": "clientStatusType.pending",
"value": "Pending"
},
"active": false,
"fullname": "Home Farm Produce",
"displayName": "Home Farm Produce",
"officeId": 1,
"officeName": "Head Office"
}
]
}
Update a Client
Note:You can update any of the basic attributes of a client using this API but not its associations.
Chaning the relationship between a client and its office is not supported through this API. An API specific to handling transfers of clients between offices will be introduced for this.
The relationship between a client and a group must be removed through the Groups API.
PUT https://DomainName/api/v1/clients/{clientId}
PUT clients/1
Content-Type: application/json
Request Body:
{
"externalId": "786444UUUYYH7"
}
{
"officeId": 1,
"clientId": 1,
"resourceId": 1,
"changes": {
"externalId": "786444UUUYYH7"
}
}
Delete a Client
If a client is in Pending state you are allowed to Delete it. The delete is a 'hard delete' and cannot be recovered from. Once clients become active or have loans or savings associated with it, you cannot delete the client but you may Close the client if they have died or exited the program.
DELETE https://DomainName/api/v1/clients/{clientId}
DELETE clients/3
Content-Type: application/json
Request Body:
{
}
{
"officeId": 1,
"clientId": 3,
"resourceId": 3
}
Retrieve client accounts overview
An example of how a loan portfolio summary can be provided. This
is requested in a specific use case of the reference application.
It is quite reasonable to add resources like this to simplify User Interface development.
Example Requests:
clients/1/accounts
clients/1/accounts?fields=loanAccounts,savingsAccounts
GET https://DomainName/api/v1/clients/{clientId}/accounts
{
"loanAccounts": [
{
"id": 1,
"accountNo": "000000001",
"externalId": "456",
"productId": 1,
"productName": "TestOne",
"status": {
"id": 300,
"code": "loanStatusType.active",
"value": "Active",
"pendingApproval": false,
"waitingForDisbursal": false,
"active": true,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"loanType": {
"id": 1,
"code": "loanType.individual",
"value": "Individual"
},
"loanCycle": 1
}
],
"savingsAccounts": [
{
"id": 7,
"accountNo": "000000007",
"productId": 2,
"productName": "Other product",
"status": {
"id": 100,
"code": "savingsAccountStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"submittedAndPendingApproval": true,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
},
{
"id": 6,
"accountNo": "000000006",
"productId": 1,
"productName": "Passbook Savings",
"status": {
"id": 300,
"code": "savingsAccountStatusType.active",
"value": "Active",
"submittedAndPendingApproval": false,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": true,
"closed": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"accountBalance": 1828.03
},
{
"id": 5,
"accountNo": "000000005",
"productId": 1,
"productName": "Passbook Savings",
"status": {
"id": 400,
"code": "savingsAccountStatusType.withdrawn.by.applicant",
"value": "Withdrawn by applicant",
"submittedAndPendingApproval": false,
"approved": false,
"rejected": false,
"withdrawnByApplicant": true,
"active": false,
"closed": true
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
}
]
}
Client Identifiers
Client Identifiers refer to documents that are
used to uniquely identify a customer
Ex: Drivers License, Passport, Ration card etc
Field Descriptions |
| documentKey |
| Number/String used to uniquely identify a particular document (Driving License number for a driving license etc) |
| documentType |
| Type of the identification document (License, Passport Etc) |
| description |
| Any user comments to be associated with the Client Identifier |
List all Identifiers for a Client
Example Requests:
clients/1/identifiers
clients/1/identifiers?fields=documentKey,documentType,description
GET https://DomainName/api/v1/clients/{clientId}/identifiers
[
{
"id": 2,
"clientId": 1,
"documentType": {
"id": 3,
"name": "Drivers License"
},
"documentKey": "12345",
"description": "Issued in the year 2--7"
}
]
Retrieve Client Identifier 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/1/identifiers/template
GET https://DomainName/api/v1/clients/{clientId}/identifiers/template
{
"allowedDocumentTypes": [
{
"id": 1,
"name": "Passport",
"position": 0
},
{
"id": 2,
"name": "Id",
"position": 0
},
{
"id": 3,
"name": "Drivers License",
"position": 0
},
{
"id": 4,
"name": "Any Other Id Type",
"position": 0
}
]
}
Retrieve a Client Identifier
Example Requests:
clients/1/identifier/2
clients/1/identifier/2?template=true
clients/1/identifiers/2?fields=documentKey,documentType,description
GET https://DomainName/api/v1/clients/{clientId}/identifiers/{identifierId}
{
"id": 2,
"clientId": 1,
"documentType": {
"id": 3,
"name": "Drivers License"
},
"documentKey": "12345",
"description": "Issued in 2007"
}
Create an Identifier for a Client
Mandatory Fields |
| documentKey, documentTypeId |
POST https://DomainName/api/v1/clients/{clientId}/identifiers
POST clients/1/identifiers
Content-Type: application/json
Request Body:
{
"documentTypeId":"1",
"documentKey":"KA-54677",
"description":"Document has been verified"
}
{
"officeId": 1,
"clientId": 1,
"resourceId": 3
}
Update a Client Identifier
PUT https://DomainName/api/v1/clients/{clientId}/identifiers/{identifierId}
PUT clients/1/identifiers/3
Content-Type: application/json
Request Body:
{
"documentTypeId":"4",
"documentKey":"KA-94667",
"description":"Document has been updated"
}
{
"officeId": 1,
"clientId": 1,
"resourceId": 3,
"changes": {
"documentTypeId": 4,
"documentKey": "KA-94667",
"description": "Document has been updated"
}
}
Delete a Client Identifier
DELETE https://DomainName/api/v1/clients/{clientId}/identifiers/{identifierId}
DELETE clients/1/identifiers/3
Content-Type: application/json
No Request Body:
{
"officeId": 1,
"clientId": 1,
"resourceId": 3
}
Client Images
The current API provides support for the addition of a single
image for a Client
Allowed formats: JPEG (.jpg or .jpeg), GIF (.gif) and PNG (.png)
The API supports two different Approaches for manipulating Client Images
- Data URI's: For easier manipulation by Javascript clients etc in supported Browsers.
- Multi-part form data: Images can be uploaded using Multi part forms and downloaded as regular binary files
Get Client Image (DATA URI)
Example Requests:
clients/1/images
GET https://DomainName/api/v1/clients/{clientId}/images
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJ
bWFnZVJlYWR5ccllPAAAAJ1JREFUeNpi+P//PwMIA4E9EG8E4idQDGLbw+WhiiqA+D8OXAFVAzbp
DxBvB2JLIGaGYkuoGEjOhhFIHAbij0BdPgxYACMj42ogJQpifwBiXSDeC8JIbt4LxSC5DyxQjTeB
+BeaYb+Q5EBOAVutCzMJHUNNPADzzDokiYdAfAmJvwLkGeTgWQfyKZICS6hYBTwc0QL8ORSjBDhA
gAEAOg13B6R/SAgAAAAASUVORK5CYII=
Get Client Image (Binary file)
GET https://DomainName/api/v1/clients/{clientId}/images
POST clients/1/images
Accept: application/octet-stream
Not shown: The corresponding binary (image) file
Upload an Image for a Client (Data URI)
POST https://DomainName/api/v1/clients/{clientId}/images
POST clients/1/images
Content-Type: text/plain
Request Body:
data:image/png;base64,iVBORw0KGgoAA
AANSUhEUgAAABAAAAAQAQMAAAAlPW0iAAAABlBMVEUAAAD///+l2Z/dAAAAM0l
EQVR4nGP4/5/h/1+G/58ZDrAz3D/McH8yw83NDDeNGe4Ug9C9zwz3gVLMDA/A6
P9/AFGGFyjOXZtQAAAAAElFTkSuQmCC
{
"resourceId": 1,
"changes": {},
"resourceIdentifier": "1"
}
Upload an Image for a Client (Multi-part Form data)
Mandatory Fields |
| file |
The form should contain a required named body part with the
name "file".
If you are using a HTML form, a snippet like
<input type="file" name="file"></input>
can be used for uploading the image file
POST https://DomainName/api/v1/clients/{clientId}/images
POST clients/1/images
Content-Type: multipart/form-data
Request Body: Not shown
{
"resourceId": 1,
"changes": {},
"resourceIdentifier": "1"
}
Update a Client Image (Data URI)
PUT https://DomainName/api/v1/clients/{clientId}/images
PUT clients/1/images
Content-Type: text/plain
Request Body:
data:image/png;base64,iVBORw0KGgoAA
AANSUhEUgAAABAAAAAQAQMAAAAlPW0iAAAABlBMVEUAAAD///+l2Z/dAAAAM0l
EQVR4nGP4/5/h/1+G/58ZDrAz3D/McH8yw83NDDeNGe4Ug9C9zwz3gVLMDA/A6
P9/AFGGFyjOXZtQAAAAAElFTkSuQmCC
{
"resourceId": 1,
"changes": {},
"resourceIdentifier": "1"
}
Update a Client Image (Multi-part Form data)
Mandatory Fields |
| file |
The form should contain a required named body part with the
name "file".
If you are using a HTML form, a snippet like
<input type="file" name="file"></input>
can be used for uploading the image file
PUT https://DomainName/api/v1/clients/{clientId}/images
PUT clients/1/images
Content-Type: multipart/form-data
Request Body: Not shown
Delete a Client Image
DELETE https://DomainName/api/v1/clients/{clientId}/images
DELETE clients/1/images
Content-Type: application/json
No Request Body:
{
"resourceId": 1,
"changes": {},
"resourceIdentifier": "1"
}
Centers
Centers along with Groups are used to provided a distinctive banking distribution channel used in microfinance. Its common in areas such as India to use Centers and Group administrative units in grameen style lending. Typically groups will contain one to five people and centers themselves will be made of anywhere between 2-7 groups.
Field Descriptions |
| externalId |
| A place to put an external reference for this center e.g. The ID another system uses. If provided, it must be unique. |
| name |
| Name given to the Center. |
| active |
| Indicates whether this center is to be created as active. If active=true, then activationDate must be provided. If active=false, then the center is created as pending. |
| activationDate |
| The date on which the center became active. |
| officeId |
| The officeId of the office/branch this center is administrated through. |
| staffId |
| The staffId of the staff member dealing with this center. The staff member is not specifically the loan officer. |
| groupMembers |
| The array of groupIds to indicate what groups are part of this center. |
Retrieve a Center Template
Example Requests:
centers/template
centers/template?officeId=2
GET https://DomainName/mifosng-provider/api/v1/centers/template
{
"active": false,
"activationDate": [
2013,
4,
18
],
"officeId": 1,
"officeOptions": [
{
"id": 1,
"name": "Head Office",
"nameDecorated": "Head Office"
},
{
"id": 2,
"name": "Branch Office 1",
"nameDecorated": "....Branch Office 1"
}
],
"staffOptions": [
{
"id": 1,
"displayName": "C, Mike"
}
],
"groupMembersOptions": [
{
"id": 1,
"name": "First Group",
"externalId": "000-1A",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".1."
},
{
"id": 2,
"name": "Pending Group",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".2."
}
]
}
GET https://DomainName/mifosng-provider/api/v1/centers/template?officeId=2
{
"active": false,
"activationDate": [
2013,
4,
18
],
"officeId": 2,
"officeOptions": [
{
"id": 1,
"name": "Head Office",
"nameDecorated": "Head Office"
},
{
"id": 2,
"name": "Branch Office 1",
"nameDecorated": "....Branch Office 1"
}
],
"staffOptions": [
{
"id": 2,
"displayName": "D, Mary"
},
{
"id": 3,
"displayName": "P, Paul"
}
]
}
Create a Center
Mandatory Fields |
| name, officeId, active, activationDate (if active=true) |
Optional Fields |
| externalId, staffId, groupMembers |
Creater a center as pending with no association to groupMembers.
POST https://DomainName/mifosng-provider/api/v1/centers
POST centers
Content-Type: application/json Request Body:
{
"name": "First Center (No groups)",
"officeId": 1,
"active": false
}
{
"officeId": 1,
"groupId": 8,
"resourceId": 8
}
Creater a center as active with no association to groupMembers.
POST https://DomainName/mifosng-provider/api/v1/centers
POST centers
Content-Type: application/json Request Body:
{
"name": "centerwithgroup",
"officeId": 1,
"groupMembers": ["7"],
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"active": true,
"activationDate": "01 March 2011"
}
{
"officeId": 1,
"groupId": 9,
"resourceId": 9
}
Activate a Center
Centers can be created in a Pending state. This API exists to enable center activation.
If the center happens to be already active this API will result in an error.
POST https://Domain Name/api/v1/centers/{centerId}?command=activate
POST centers/1?command=activate
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"activationDate": "01 March 2011"
}
{
"officeId": 1,
"groupId": 1,
"resourceId": 1
}
Update a Center
PUT https://DomainName/mifosng-provider/api/v1/centers/{centerId}
PUT centers/8
Content-Type: application/json
Request Body:
{
"name": "First Center (No groups)",
}
{
"officeId": 1,
"groupId": 8,
"resourceId": 8,
"changes": {
"name": "First Center (No groups) - modified"
}
}
Delete a Center
A center can be delete if it is in pending state and has nothing associated with it - groups, loans, savings etc
POST https://DomainName/mifosng-provider/api/v1/centers/{centerId}
DELETE centers/8
{
"resourceId":1,
"changes":{}
}
Retrieve a Center
Example Requests:
centers/1
centers/1?associations=groupMembers
Retrieve an existing center with no groups information.
GET https://DomainName/mifosng-provider/api/v1/centers/8
{
"id": 8,
"status": {
"id": 100,
"code": "groupingStatusType.pending",
"value": "Pending"
},
"active": false,
"name": "First Center (No groups)",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".8."
}
Retrieve an existing center with no groups information.
GET https://DomainName/mifosng-provider/api/v1/centers/9?associations=groupMembers
{
"id": 9,
"status": {
"id": 300,
"code": "groupingStatusType.active",
"value": "Active"
},
"active": true,
"activationDate": [
2011,
3,
1
],
"name": "centerwithgroup",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".9.",
"groupMembers": [
{
"id": 7,
"name": "Othergroup",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".7."
}
]
}
List Centers
The list capability of centers can support pagination and sorting.
Optional Arguments
- offset
- Integer optional, defaults to 0
- Indicates from what result to start from.
- limit
- Integer optional, defaults to 200
- Restricts the size of results returned. To override the default and return all entries you must explicitly pass a non-positive integer value for limit e.g. limit=0, or limit=-1
- orderBy
- String optional, one of displayName, accountNo, officeId, officeName
- Orders the results by the field indicated.
- sortBy
- String optional, one of ASC, DESC
- Indicates what way to order results if orderBy is used.
- officeId
- Integer optional
- Provides ability to restrict list of centers returned based on the office there associated with.
- underHierarchy
- String optional
- Use the office hierarchy string to return all centers under a given hierarchy.
- name
- String optional
- Use name of centers to restrict results.
- externalId
- String optional
- Use externalId of center to restrict results.
- sqlSearch
- String optional
- Use an sql fragment valid for the underlying center schema to filter results. e.g. display_name like %K%
Example Requests:
centers
centers?fields=name,officeName,joinedDate
centers?offset=10&limit=50
centers?orderBy=name,sortOrder=DESC
GET https://DomainName/mifosng-provider/api/v1/centers
{
"totalFilteredRecords": 2,
"pageItems": [
{
"id": 2,
"status": {
"id": 100,
"code": "groupingStatusType.pending",
"value": "Pending"
},
"active": false,
"name": "Center 1",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".2."
},
{
"id": 3,
"status": {
"id": 100,
"code": "groupingStatusType.pending",
"value": "Pending"
},
"active": false,
"name": "Center 2",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".3."
}
]
}
Groups
Groups are used to provide a distinctive banking distribution channel used in microfinance throughout the world. The Group is an administrative unit. It can contain as few as 5 people or as many as 40 depending on how its used.
Different styles of group lending - Joint-Liability Group, Grameen Model (Center-Group), Self-Help Groups, Village/Communal Banks)
Field Descriptions |
| name |
| Name given to the Group. |
| externalId |
| A place to put an external reference for this group e.g. The ID another system uses. If provided, it must be unique. |
| officeId |
| The officeId of the office/branch this group is administrated through. |
| active |
| Indicates whether this group is to be created as active. If active=true, then activationDate must be provided. If active=false, then the group is created as pending. |
| activationDate |
| The date on which the group became active. |
| staffId |
| The staffId of the staff member dealing with this group. The staff member is not specifically the loan officer. The staff member must be assigned to the same office as this group. |
| clientMembers |
| The individual client members that make up the group. The clients must be assigned to the same office as this group. |
Retrieve Group 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
- officeId
- Integer optional
- centerId
- Integer optional
- staffInSelectedOfficeOnly
- Boolean optional
- Defaults to false if not provided. If staffInSelectedOfficeOnly=true only staff who are associated with the selected branch are returned.
Example Requests:
groups/template
groups/template?officeId=2
groups/template?centerId=1
groups/template?centerId=1&staffInSelectedOfficeOnly=true
Template to create a standard group
GET https://DomainName/mifosng-provider/api/v1/groups/template
{
"officeId": 1,
"officeOptions": [
{
"id": 1,
"name": "Head Office",
"nameDecorated": "Head Office"
},
{
"id": 2,
"name": "Branch Office 1",
"nameDecorated": "....Branch Office 1"
}
],
"staffOptions": [
{
"id": 1,
"displayName": "C, Mike"
}
],
"clientOptions": [
{
"id": 1,
"displayName": "Petra Yton",
"officeId": 1,
"officeName": "Head Office"
},
{
"id": 2,
"displayName": "Small shop business",
"officeId": 1,
"officeName": "Head Office"
}
]
}
Template to create a standard group with specific office known. This will return only staffOptions and clientMembersOptions relevant for the chosen office.
GET https://DomainName/mifosng-provider/api/v1/groups/template?officeId=2
{
"officeId": 2,
"officeOptions": [
{
"id": 1,
"name": "Head Office",
"nameDecorated": "Head Office"
},
{
"id": 2,
"name": "Branch Office 1",
"nameDecorated": "....Branch Office 1"
}
],
"staffOptions": [
{
"id": 2,
"displayName": "D, Mary"
},
{
"id": 3,
"displayName": "P, Paul"
}
]
}
Template to create a group for an existing center. As an existing center will be assigned to an office, this will return only staffOptions and clientMembersOptions relevant for the chosen center/office.
GET https://DomainName/mifosng-provider/api/v1/groups/template?centerId=1
Create a Group
Mandatory Fields |
| name, officeId, active, activationDate (if active=true) |
Optional Fields |
| externalId,staffId,clientMembers |
POST https://DomainName/mifosng-provider/api/v1/groups
POST groups
Content-Type: application/json Request Body:
{
"officeId":"1",
"name":"Pending Group",
"active": false
}
{
"officeId": 1,
"groupId": 2,
"resourceId": 2
}
POST groups
Content-Type: application/json Request Body:
{
"officeId":"1",
"name":"First Group",
"externalId": "000-1A",
"clientMembers": ["1"],
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"active": true,
"activationDate": "04 March 2009",
"submittedOnDate":"04 March 2009"
}
{
"officeId": 1,
"groupId": 1,
"resourceId": 1
}
Activate a Group
Groups can be created in a Pending state. This API exists to enable group activation.
If the group happens to be already active this API will result in an error.
POST https://Domain Name/api/v1/groups/{groupId}?command=activate
POST groups/1?command=activate
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"activationDate": "01 March 2011"
}
{
"officeId": 1,
"groupId": 1,
"resourceId": 1
}
Associate Clients
This API allows to associate existing clients to a group.
The clients are listed from the office to which the group is associated.
If client(s) is already associated with group then API will result in an error.
POST https://Domain Name/api/v1/groups/{groupId}?command=associateClients
POST groups/1?command=associateClients
Content-Type: application/json
Request Body:
{
"clientMembers":[1,2]
}
{
"officeId": 1,
"groupId": 1,
"resourceId": 1,
"clientMembers": [1,2]
}
Disassociate Clients
This API allows to disassociate clients from a group.
Disassociating a client with group loans results in an error.
POST https://Domain Name/api/v1/groups/{groupId}?command=disassociateClients
POST groups/1?command=disassociateClients
Content-Type: application/json
Request Body:
{
"clientMembers":[1,2]
}
{
"officeId": 1,
"groupId": 1,
"resourceId": 1,
"clientMembers": [1,2]
}
Associate Clients
This API allows to associate existing clients to a group.
The clients are listed from the office to which the group is associated.
If client(s) is already associated with group then API will result in an error.
POST https://Domain Name/api/v1/groups/{groupId}?command=associateClients
POST groups/1?command=associateClients
Content-Type: application/json
Request Body:
{
"clientMembers":[1,2]
}
{
"officeId": 1,
"groupId": 1,
"resourceId": 1,
"clientMembers": [1,2]
}
Transfer Clients across groups
This API allows to transfer clients from one group to another
Field Descriptions |
| destinationGroupId |
| The identifier of the group to which the clients are to be transferred ( has to be in the same branch as the source Group). |
| clients |
| Identifiers of all clients who need to be transferred |
| inheritDestinationGroupLoanOfficer |
| Flag specifies if the transferred clients (and all their active loans) should be linked to the assigned loan officer for the group |
Mandatory Fields |
| destinationGroupId, clients |
Optional Fields |
| inheritDestinationGroupLoanOfficer (defaults to true), transferActiveLoans (defaults to true) |
POST https://Domain Name/api/v1/groups/{groupId}?command=transferClients
POST groups/1?command=transferClients
Content-Type: application/json
Request Body:
{
destinationGroupId:2,
clients:[{id:1}]
}
{
"resourceId": 1
}
Retrieve a Group
Example Requests:
groups/1
groups/1?associations=clientMembers
Group with no clientMembers information requested.
GET https://DomainName/mifosng-provider/api/v1/groups/1
{
"id": 1,
"name": "First Group",
"externalId": "000-1A",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".1.",
"timeline": {
"activatedOnDate": [
2013,
11,
14
],
"activatedByUsername": "mifos",
"activatedByFirstname": "App",
"activatedByLastname": "Administrator"
}
}
Group with clientMembers.
GET https://DomainName/mifosng-provider/api/v1/groups/1?associations=clientMembers
{
"id": 1,
"name": "First Group",
"externalId": "000-1A",
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".1.",
"timeline": {
"activatedOnDate": [
2013,
11,
14
],
"activatedByUsername": "mifos",
"activatedByFirstname": "App",
"activatedByLastname": "Administrator"
},
"clientMembers": [
{
"id": 1,
"accountNo": "000000001",
"externalId": "786YYH7",
"activationDate": [
2009,
3,
4
],
"firstname": "Petra",
"lastname": "Yton",
"displayName": "Petra Yton",
"officeId": 1,
"officeName": "Head Office"
}
]
}
Retrieve Group accounts overview
An example of how a loan portfolio summary can be provided. This
is requested in a specific use case of the reference application.
It is quite reasonable to add resources like this to simplify User Interface development.
Example Requests:
groups/1/accounts
groups/1/accounts?fields=loanAccounts,savingsAccounts,memberLoanAccounts,
memberSavingsAccounts
memberSavingsAccounts
GET https://DomainName/api/v1/groups/{groupId}/accounts
{
"loanAccounts": [
{
"id": 3,
"accountNo": "000000003",
"productId": 3,
"productName": "daily product",
"status": {
"id": 100,
"code": "loanStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"pendingApproval": true,
"waitingForDisbursal": false,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"loanType": {
"id": 2,
"code": "accountType.group",
"value": "Group"
}
}
],
"savingsAccounts": [
{
"id": 9,
"accountNo": "000000009",
"productId": 1,
"productName": "p_sav",
"status": {
"id": 100,
"code": "savingsAccountStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"submittedAndPendingApproval": true,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"accountType": {
"id": 2,
"code": "accountType.group",
"value": "Group"
}
},
{
"id": 4,
"accountNo": "000000004",
"productId": 1,
"productName": "p_sav",
"status": {
"id": 300,
"code": "savingsAccountStatusType.active",
"value": "Active",
"submittedAndPendingApproval": false,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": true,
"closed": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"accountType": {
"id": 2,
"code": "accountType.group",
"value": "Group"
}
}
],
"memberLoanAccounts": [
{
"id": 4,
"accountNo": "000000004",
"productId": 1,
"productName": "testLoan",
"status": {
"id": 200,
"code": "loanStatusType.approved",
"value": "Approved",
"pendingApproval": false,
"waitingForDisbursal": true,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"loanType": {
"id": 3,
"code": "accountType.jlg",
"value": "JLG"
}
},
{
"id": 7,
"accountNo": "000000007",
"productId": 2,
"productName": "weekly product",
"status": {
"id": 100,
"code": "loanStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"pendingApproval": true,
"waitingForDisbursal": false,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"loanType": {
"id": 3,
"code": "accountType.jlg",
"value": "JLG"
}
}
],
"memberSavingsAccounts": [
{
"id": 3,
"accountNo": "000000003",
"productId": 1,
"productName": "p_sav",
"status": {
"id": 100,
"code": "savingsAccountStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"submittedAndPendingApproval": true,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"accountType": {
"id": 3,
"code": "accountType.jlg",
"value": "JLG"
}
},
{
"id": 10,
"accountNo": "000000010",
"productId": 1,
"productName": "p_sav",
"status": {
"id": 100,
"code": "savingsAccountStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"submittedAndPendingApproval": true,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"accountType": {
"id": 3,
"code": "accountType.jlg",
"value": "JLG"
}
}
]
}
Update a Group
PUT https://DomainName/mifosng-provider/api/v1/groups/{groupid}
PUT groups/1
Content-Type: application/json
Request Body:
{
"name": "First Group (changed)"
}
{
"officeId": 1,
"groupId": 1,
"resourceId": 1,
"changes": {
"name": "First Group (changed)"
}
}
Delete a Group
A group can be deleted if it is in pending state and has nothing associated with it - groups, loans, savings etc
POST https://DomainName/mifosng-provider/api/v1/groups/{groupid}
DELETE groups/2
{
"officeId": 1,
"groupId": 2,
"resourceId": 2
}
List Groups
The list capability of groups can support pagination and sorting.
Optional Arguments
- offset
- Integer optional, defaults to 0
- Indicates from what result to start from.
- limit
- Integer optional, defaults to 200
- Restricts the size of results returned. To override the default and return all entries you must explicitly pass a non-positive integer value for limit e.g. limit=0, or limit=-1
- orderBy
- String optional, one of displayName, accountNo, officeId, officeName
- Orders the results by the field indicated.
- sortBy
- String optional, one of ASC, DESC
- Indicates what way to order results if orderBy is used.
- officeId
- Integer optional
- Provides ability to restrict list of groups returned based on the office there associated with.
- underHierarchy
- String optional
- Use the office hierarchy string to return all groups under a given hierarchy.
- name
- String optional
- Use name of groups to restrict results.
- externalId
- String optional
- Use externalId of groups to restrict results.
- sqlSearch
- String optional
- Use an sql fragment valid for the underlying group schema to filter results. e.g. display_name like %K%
Example Requests:
groups
groups?fields=name,officeName,joinedDate
groups?offset=10&limit=50
groups?orderBy=name,sortOrder=DESC
GET https://DomainName/mifosng-provider/api/v1/groups
{
"totalFilteredRecords": 2,
"pageItems": [
{
"id": 4,
"name": "AnotherGroup",
"status": {
"id": 100,
"code": "clientStatusType.pending",
"value": "Pending"
},
"active": false,
"officeId": 1,
"officeName": "Head Office",
"hierarchy": ".4."
}
]
}
Loans
The API concept of loans models the loan application process and the loan contract/monitoring process.
Field Descriptions |
| accountNo |
| The account no. associated with this loan. Is auto generated if not provided at loan application creation time. |
| externalId |
| A place to put an external reference for
this loan e.g. The ID another system uses. If provided, it must be unique. |
| fundId |
| Optional: For associating a loan with a given fund. |
| loanOfficerId |
| Optional: For associating a loan with a given staff member who is a loan officer. |
| loanPurposeId |
| Optional: For marking a loan with a given loan purpose option. Loan purposes are configurable and can be setup by system admin through code/code values screens. |
| principal |
| The loan amount to be disbursed to through loan. |
| loanTermFrequency |
| The length of loan term Used like: loanTermFrequency loanTermFrequencyType e.g. 12 Months |
| loanTermFrequencyType |
| The loan term period to use. Used like:
loanTermFrequency loanTermFrequencyType e.g. 12 Months Example Values: 0=Days, 1=Weeks, 2=Months, 3=Years |
| numberOfRepayments |
| Number of installments to repay. Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType e.g. 10 (repayments) Every 12 Weeks |
| repaymentEvery |
| Used like: numberOfRepayments Every
repaymentEvery repaymentFrequencyType e.g. 10 (repayments) Every 12 Weeks |
| repaymentFrequencyType |
| Used like: numberOfRepayments Every
repaymentEvery repaymentFrequencyType e.g. 10 (repayments) Every 12 Weeks Example Values: 0=Days, 1=Weeks, 2=Months |
| interestRatePerPeriod |
| Interest Rate. Used like: interestRatePerPeriod % interestRateFrequencyType - interestType e.g. 12.0000% Per year - Declining Balance |
| interestRateFrequencyType |
| Used like: interestRatePerPeriod%
interestRateFrequencyType - interestType e.g. 12.0000% Per year - Declining Balance Example Values: 2=Per month, 3=Per year |
| graceOnPrincipalPayment |
| Optional: Integer - represents the number of repayment periods that grace should apply to the principal component of a repayment period. |
| graceOnInterestPayment |
| Optional: Integer - represents the number of repayment periods that grace should apply to the interest component of a repayment period. Interest is still calculated but offset to later repayment periods. |
| graceOnInterestCharged |
| Optional: Integer - represents the number of repayment periods that should be interest-free. |
| interestChargedFromDate |
| Optional: Date - The date from with interest is to start being charged. |
| expectedDisbursementDate |
| The proposed disbursement date of the loan so a proposed repayment schedule can be provided. |
| submittedOnDate |
| The date the loan application was submitted by applicant. |
| linkAccountId |
| The Savings Account id for linking with loan account for payments. |
| amortizationType |
| Example Values: 0=Equal principle payments, 1=Equal installments |
| interestType |
| Used like: interestRatePerPeriod%
interestRateFrequencyType - interestType e.g. 12.0000% Per year - Declining Balance Example Values: 0=Declining Balance, 1=Flat |
| interestCalculationPeriodType |
| Example Values: 0=Daily, 1=Same as repayment period |
| 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. |
| transactionProcessingStrategyId |
|
An enumeration that indicates the type of transaction processing strategy to be used. This relates to functionality that is also known as Payment Application Logic.
A number of out of the box appraches exist, some are custom to specific MFIs, some are more general and indicate the order in which payments are processed. Refer to the Payment Application Logic / Transaction Processing Strategy section in the appendix for more detailed overview of each available payment application logic provided out of the box. List of current approaches:
|
| loanType |
| To represent different type of loans. At present there are three type of loans are supported. Available loan types:
|
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
- templateType
- String mandatory, allowed values are individual, group, jlg, jlgbulk
-
templateType value decides the required template data for creating a new loan application. -
'individual': Loan template data for creating individual loans. - 'group': Loan template data for creating a group loan (loan given to group as a whole).
- 'jlg': Loan template data for creating a Joint liability group loan for a client.
- 'jlgbulk': Loan template data for creating a Joint liability group loan for multiple clients at a time in a group.
- clientId
- Integer mandatory
- productId
- Integer optional
- If entered, productId, productName and selectedProduct fields are returned.
- staffInSelectedOfficeOnly
- Boolean optional
- Defaults to false if not provided. If staffInSelectedOfficeOnly=true only loan officers who are associated with the selected branch are returned.
Example Requests:
loans/template?templateType=individual&clientId=1
loans/template?templateType=individual&clientId=1&productId=1
GET https://DomainName/api/v1/loans/template?templateType=individual&clientId=1
{
"clientId": 1,
"clientName": "Kampala first Client",
"clientOfficeId": 2,
"timeline": {
"expectedDisbursementDate": [
2013,
3,
8
]
},
"productOptions": [
{
"id": 1,
"name": "Kampala Product (with cash accounting)"
}
]
}
GET https://DomainName/api/v1/loans/template?templateType=individual&clientId=1&productId=1
{
"clientId": 1,
"clientName": "Kampala first Client",
"clientOfficeId": 2,
"loanProductId": 1,
"loanProductName": "Kampala Product (with cash accounting)",
"loanProductDescription": "Typical Kampala loan product with cash accounting enabled for testing.",
"currency": {
"code": "UGX",
"name": "Uganda Shilling",
"decimalPlaces": 2,
"displaySymbol": "USh",
"nameCode": "currency.UGX",
"displayLabel": "Uganda Shilling (USh)"
},
"principal": 1000000,
"termFrequency": 12,
"termPeriodFrequencyType": {
"id": 2,
"code": "repaymentFrequency.periodFrequencyType.months",
"value": "Months"
},
"numberOfRepayments": 12,
"repaymentEvery": 1,
"repaymentFrequencyType": {
"id": 2,
"code": "repaymentFrequency.periodFrequencyType.months",
"value": "Months"
},
"interestRatePerPeriod": 24,
"interestRateFrequencyType": {
"id": 3,
"code": "interestRateFrequency.periodFrequencyType.years",
"value": "Per year"
},
"annualInterestRate": 24,
"amortizationType": {
"id": 1,
"code": "amortizationType.equal.installments",
"value": "Equal installments"
},
"interestType": {
"id": 1,
"code": "interestType.flat",
"value": "Flat"
},
"interestCalculationPeriodType": {
"id": 1,
"code": "interestCalculationPeriodType.same.as.repayment.period",
"value": "Same as repayment period"
},
"transactionProcessingStrategyId": 2,
"timeline": {
"expectedDisbursementDate": [
2013,
3,
8
]
},
"charges": [],
"productOptions": [
{
"id": 1,
"name": "Kampala Product (with cash accounting)"
}
],
"loanOfficerOptions": [
{
"id": 2,
"firstname": "Kampala",
"lastname": "LoanOfficer",
"displayName": "LoanOfficer, Kampala",
"officeId": 2,
"officeName": "Uganda (Kampala)",
"isLoanOfficer": true
}
],
"loanPurposeOptions": [
{
"id": 20,
"name": "option.Agriculture",
"position": 1
},
{
"id": 21,
"name": "option.Manufacturing",
"position": 20
},
{
"id": 22,
"name": "option.HousingImprovement",
"position": 21
}
],
"termFrequencyTypeOptions": [
{
"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"
}
],
"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"
}
],
"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"
}
],
"transactionProcessingStrategyOptions": [
{
"id": 2,
"code": "heavensfamily-strategy",
"name": "Heavensfamily"
}
],
"chargeOptions": [
{
"id": 1,
"name": "Bank Fee (per installment)",
"active": true,
"penalty": false,
"currency": {
"code": "UGX",
"name": "Uganda Shilling",
"decimalPlaces": 2,
"displaySymbol": "USh",
"nameCode": "currency.UGX",
"displayLabel": "Uganda Shilling (USh)"
},
"amount": 1500,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
}
}
],
"loanCollateralOptions": [
{
"id": 17,
"name": "option.House",
"position": 1
},
{
"id": 18,
"name": "option.Television",
"position": 17
},
{
"id": 19,
"name": "option.Gold",
"position": 18
}
],
"accountLinkingOptions":[
{
"id":1,
"accountNo":"000000001",
"clientId":1,
"clientName":"pramod nuthakki",
"productId":1,
"productName":"pramod sav",
"fieldOfficerId":0,
"currency":{"code":"USD","name":"US Dollar","decimalPlaces":2,"displaySymbol":"$","nameCode":"currency.USD","displayLabel":"US Dollar ($)"}
}
]
}
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.
- 'repaymentSchedule': Loan schedule data.
- 'transactions': Loan transactions data.
- 'charges': Loan charges data.
- 'guarantors': Loan guarantors data.
- 'collateral': Loan collateral data.
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://DomainName/api/v1/loans/{loanId}
{
"id": 1,
"accountNo": "000000001",
"status": {
"id": 300,
"code": "loanStatusType.active",
"value": "Active",
"pendingApproval": false,
"waitingForDisbursal": false,
"active": true,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"clientId": 1,
"clientName": "Kampala first Client",
"clientOfficeId": 2,
"loanProductId": 1,
"loanProductName": "Kampala Product (with cash accounting)",
"loanProductDescription": "Typical Kampala loan product with cash accounting enabled for testing.",
"loanPurposeId": 22,
"loanPurposeName": "option.HousingImprovement",
"loanOfficerId": 2,
"loanOfficerName": "LoanOfficer, Kampala",
"loanType": {
"id": 1,
"code": "loanType.individual",
"value": "Individual"
},
"currency": {
"code": "UGX",
"name": "Uganda Shilling",
"decimalPlaces": 2,
"displaySymbol": "USh",
"nameCode": "currency.UGX",
"displayLabel": "Uganda Shilling (USh)"
},
"principal": 1000000,
"termFrequency": 12,
"termPeriodFrequencyType": {
"id": 2,
"code": "termFrequency.periodFrequencyType.months",
"value": "Months"
},
"numberOfRepayments": 12,
"repaymentEvery": 1,
"repaymentFrequencyType": {
"id": 2,
"code": "repaymentFrequency.periodFrequencyType.months",
"value": "Months"
},
"interestRatePerPeriod": 24,
"interestRateFrequencyType": {
"id": 3,
"code": "interestRateFrequency.periodFrequencyType.years",
"value": "Per year"
},
"annualInterestRate": 24,
"amortizationType": {
"id": 1,
"code": "amortizationType.equal.installments",
"value": "Equal installments"
},
"interestType": {
"id": 1,
"code": "interestType.flat",
"value": "Flat"
},
"interestCalculationPeriodType": {
"id": 1,
"code": "interestCalculationPeriodType.same.as.repayment.period",
"value": "Same as repayment period"
},
"transactionProcessingStrategyId": 2,
"timeline": {
"submittedOnDate": [
2012,
4,
3
],
"submittedByUsername": "admin",
"submittedByFirstname": "App",
"submittedByLastname": "Administrator",
"approvedOnDate": [
2012,
4,
3
],
"approvedByUsername": "admin",
"approvedByFirstname": "App",
"approvedByLastname": "Administrator",
"expectedDisbursementDate": [
2012,
4,
10
],
"actualDisbursementDate": [
2012,
4,
10
],
"disbursedByUsername": "admin",
"disbursedByFirstname": "App",
"disbursedByLastname": "Administrator",
"expectedMaturityDate": [
2013,
4,
10
]
},
"summary": {
"currency": {
"code": "UGX",
"name": "Uganda Shilling",
"decimalPlaces": 2,
"displaySymbol": "USh",
"nameCode": "currency.UGX",
"displayLabel": "Uganda Shilling (USh)"
},
"principalDisbursed": 1000000,
"principalPaid": 0,
"principalWrittenOff": 0,
"principalOutstanding": 1000000,
"principalOverdue": 833333.3,
"interestCharged": 240000,
"interestPaid": 0,
"interestWaived": 0,
"interestWrittenOff": 0,
"interestOutstanding": 240000,
"interestOverdue": 200000,
"feeChargesCharged": 18000,
"feeChargesDueAtDisbursementCharged": 0,
"feeChargesPaid": 0,
"feeChargesWaived": 0,
"feeChargesWrittenOff": 0,
"feeChargesOutstanding": 18000,
"feeChargesOverdue": 15000,
"penaltyChargesCharged": 0,
"penaltyChargesPaid": 0,
"penaltyChargesWaived": 0,
"penaltyChargesWrittenOff": 0,
"penaltyChargesOutstanding": 0,
"penaltyChargesOverdue": 0,
"totalExpectedRepayment": 1258000,
"totalRepayment": 0,
"totalExpectedCostOfLoan": 258000,
"totalCostOfLoan": 0,
"totalWaived": 0,
"totalWrittenOff": 0,
"totalOutstanding": 1258000,
"totalOverdue": 1048333.3,
"overdueSinceDate": [
2012,
5,
10
],
"linkedAccount":{
"id":1,
"accountNo":"000000001"
}
}
}
List Loans
The list capability of loans can support pagination and sorting.
Optional Arguments
- offset
- Integer optional, defaults to 0
- Indicates from what result to start from.
- limit
- Integer optional, defaults to 200
- Restricts the size of results returned. To override the default and return all entries you must explicitly pass a non-positive integer value for limit e.g. limit=0, or limit=-1
- orderBy
- String optional, one of displayName, accountNo, officeId, officeName
- Orders the results by the field indicated.
- sortBy
- String optional, one of ASC, DESC
- Indicates what way to order results if orderBy is used.
- officeId
- Integer optional
- Provides ability to restrict list of loans returned based on the office there associated with.
- underHierarchy
- String optional
- Use the office hierarchy string to return all loans under a given hierarchy.
- accountNo
- String optional
- Use account no. of loans to restrict results.
- externalId
- String optional
- Use externalId of loan to restrict results.
- sqlSearch
- String optional
- Use an sql fragment valid for the underlying loan schema to filter results. e.g. display_name like %K%
Example Requests:
loans
loans?fields=accountNo
loans?offset=10&limit=50
loans?orderBy=accountNo,sortOrder=DESC
GET https://DomainName/mifosng-provider/api/v1/loans
{
"totalFilteredRecords": 1,
"pageItems": [
{
"id": 1,
"accountNo": "000000001",
"status": {
"id": 300,
"code": "loanStatusType.active",
"value": "Active",
"pendingApproval": false,
"waitingForDisbursal": false,
"active": true,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"clientId": 1,
"clientName": "Change To IndividualName",
"clientOfficeId": 1,
"loanProductId": 1,
"loanProductName": "AgriCredit",
"loanProductDescription": "test",
"loanType": {
"id": 1,
"code": "loanType.individual",
"value": "Individual"
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"principal": 10000,
"termFrequency": 12,
"termPeriodFrequencyType": {
"id": 2,
"code": "termFrequency.periodFrequencyType.months",
"value": "Months"
},
"numberOfRepayments": 12,
"repaymentEvery": 1,
"repaymentFrequencyType": {
"id": 2,
"code": "repaymentFrequency.periodFrequencyType.months",
"value": "Months"
},
"interestRatePerPeriod": 2,
"interestRateFrequencyType": {
"id": 2,
"code": "interestRateFrequency.periodFrequencyType.months",
"value": "Per month"
},
"annualInterestRate": 24,
"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"
},
"transactionProcessingStrategyId": 2,
"timeline": {
"submittedOnDate": [
2012,
6,
1
],
"submittedByUsername": "mifos",
"submittedByFirstname": "App",
"submittedByLastname": "Administrator",
"approvedOnDate": [
2012,
6,
1
],
"approvedByUsername": "mifos",
"approvedByFirstname": "App",
"approvedByLastname": "Administrator",
"expectedDisbursementDate": [
2012,
6,
1
],
"actualDisbursementDate": [
2012,
6,
1
],
"disbursedByUsername": "mifos",
"disbursedByFirstname": "App",
"disbursedByLastname": "Administrator",
"expectedMaturityDate": [
2013,
6,
1
]
},
"linkedAccount":{
"id":1,
"accountNo":"000000001"
},
"summary": {
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"principalDisbursed": 10000,
"principalPaid": 3073.07,
"principalWrittenOff": 0,
"principalOutstanding": 6926.93,
"principalOverdue": 5999.92,
"interestCharged": 1347.15,
"interestPaid": 709.33,
"interestWaived": 0,
"interestWrittenOff": 0,
"interestOutstanding": 637.82,
"interestOverdue": 619.28,
"feeChargesCharged": 0,
"feeChargesDueAtDisbursementCharged": 0,
"feeChargesPaid": 0,
"feeChargesWaived": 0,
"feeChargesWrittenOff": 0,
"feeChargesOutstanding": 0,
"feeChargesOverdue": 0,
"penaltyChargesCharged": 0,
"penaltyChargesPaid": 0,
"penaltyChargesWaived": 0,
"penaltyChargesWrittenOff": 0,
"penaltyChargesOutstanding": 0,
"penaltyChargesOverdue": 0,
"totalExpectedRepayment": 11347.15,
"totalRepayment": 3782.4,
"totalExpectedCostOfLoan": 1347.15,
"totalCostOfLoan": 709.33,
"totalWaived": 0,
"totalWrittenOff": 0,
"totalOutstanding": 7564.75,
"totalOverdue": 6619.2,
"overdueSinceDate": [
2012,
11,
1
]
},
"feeChargesAtDisbursementCharged": 0
}
]
}
Calculate loan repayment schedule
Mandatory Fields |
| productId, principal, loanTermFrequency, loanTermFrequencyType, numberOfRepayments, repaymentEvery, repaymentFrequencyType, interestRatePerPeriod, amortizationType, interestType, interestCalculationPeriodType, expectedDisbursementDate, transactionProcessingStrategyId |
POST https://DomainName/api/v1/loans?command=calculateLoanSchedule
POST loans?command=calculateLoanSchedule
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en_GB",
"productId": 1,
"principal": "100,000.00",
"loanTermFrequency": 12,
"loanTermFrequencyType": 2,
"numberOfRepayments": 12,
"repaymentEvery": 1,
"repaymentFrequencyType": 2,
"interestRatePerPeriod": 2,
"amortizationType": 1,
"interestType": 0,
"interestCalculationPeriodType": 1,
"expectedDisbursementDate": "20 September 2011",
"transactionProcessingStrategyId": 2
}
{
"currency": {
"code": "UGX",
"name": "Uganda Shilling",
"decimalPlaces": 2,
"displaySymbol": "USh",
"nameCode": "currency.UGX",
"displayLabel": "Uganda Shilling (USh)"
},
"loanTermInDays": 366,
"totalPrincipalDisbursed": 100000,
"totalPrincipalExpected": 100000,
"totalPrincipalPaid": 0,
"totalInterestCharged": 13471.52,
"totalFeeChargesCharged": 0,
"totalPenaltyChargesCharged": 0,
"totalWaived": 0,
"totalWrittenOff": 0,
"totalRepaymentExpected": 113471.52,
"totalRepayment": 0,
"totalOutstanding": 0,
"periods": [
{
"period": 0,
"dueDate": [
2011,
9,
20
],
"principalDisbursed": 100000,
"principalLoanBalanceOutstanding": 100000,
"feeChargesDue": 0,
"feeChargesOutstanding": 0,
"totalOriginalDueForPeriod": 0,
"totalDueForPeriod": 0,
"totalOutstandingForPeriod": 0,
"totalOverdue": 0,
"totalActualCostOfLoanForPeriod": 0
},
{
"period": 1,
"fromDate": [
2011,
9,
20
],
"dueDate": [
2011,
10,
20
],
"daysInPeriod": 30,
"principalOriginalDue": 7455.96,
"principalDue": 7455.96,
"principalOutstanding": 7455.96,
"principalLoanBalanceOutstanding": 92544.04,
"interestOriginalDue": 2000,
"interestDue": 2000,
"interestOutstanding": 2000,
"feeChargesDue": 0,
"penaltyChargesDue": 0,
"totalOriginalDueForPeriod": 9455.96,
"totalDueForPeriod": 9455.96,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 9455.96,
"totalOverdue": 9455.96,
"totalActualCostOfLoanForPeriod": 2000
},
...
...
{
"period": 12,
"fromDate": [
2012,
8,
20
],
"dueDate": [
2012,
9,
20
],
"daysInPeriod": 31,
"principalOriginalDue": 9270.56,
"principalDue": 9270.56,
"principalOutstanding": 9270.56,
"principalLoanBalanceOutstanding": 0,
"interestOriginalDue": 185.4,
"interestDue": 185.4,
"interestOutstanding": 185.4,
"feeChargesDue": 0,
"penaltyChargesDue": 0,
"totalOriginalDueForPeriod": 9455.96,
"totalDueForPeriod": 9455.96,
"totalPaidForPeriod": 0,
"totalOutstandingForPeriod": 9455.96,
"totalOverdue": 9455.96,
"totalActualCostOfLoanForPeriod": 185.4
}
]
}
Submit a new Loan Application
Mandatory Fields |
| clientId, productId, principal, loanTermFrequency, loanTermFrequencyType, loanType, numberOfRepayments, repaymentEvery, repaymentFrequencyType, interestRatePerPeriod, amortizationType, interestType, interestCalculationPeriodType, transactionProcessingStrategyId, expectedDisbursementDate, submittedOnDate, loanType |
Optional Fields |
| graceOnPrincipalPayment, graceOnInterestPayment, graceOnInterestCharged,linkAccountId |
POST https://DomainName/api/v1/loans
POST loans
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en_GB",
"clientId": 1,
"productId": 1,
"principal": "10,000.00",
"loanTermFrequency": 12,
"loanTermFrequencyType": 2,
"loanType": "individual",
"numberOfRepayments": 10,
"repaymentEvery": 1,
"repaymentFrequencyType": 2,
"interestRatePerPeriod": 10,
"amortizationType": 1,
"interestType": 0,
"interestCalculationPeriodType": 1,
"transactionProcessingStrategyId": 1,
"expectedDisbursementDate": "10 Jun 2013",
"submittedOnDate": "10 Jun 2013"
"linkAccountId" : "1"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 1
}
Approve Loan Application
Mandatory Fields |
| approvedOnDate |
POST https://DomainName/api/v1/loans/{loanId}?command=approve
POST loans/1?command=approve
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"approvedOnDate": "20 September 2011",
"note": "Loan approval note"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 200,
"code": "loanStatusType.approved",
"value": "Approved",
"pendingApproval": false,
"waitingForDisbursal": true,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"approvedOnDate": "20 September 2011",
"note": "Loan approval note"
}
}
Undo Loan Application Approval
POST https://DomainName/api/v1/loans/{loanId}?command=undoApproval
POST loans/1?command=undoApproval
Content-Type: application/json
Request Body:
{
"note": "Loan undo approval note"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 100,
"code": "loanStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"pendingApproval": true,
"waitingForDisbursal": false,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"approvedOnDate": ""
}
}
Reject Loan Application
Mandatory Fields |
| rejectedOnDate |
POST https://DomainName/api/v1/loans/{loanId}?command=reject
POST loans/1?command=reject
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"rejectedOnDate": "20 September 2011",
"note": "Loan rejection reason."
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 500,
"code": "loanStatusType.rejected",
"value": "Rejected",
"pendingApproval": false,
"waitingForDisbursal": false,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"rejectedOnDate": "20 September 2011",
"closedOnDate": "20 September 2011"
}
}
Applicant Withdraws from Loan Application
Mandatory Fields |
| withdrawnOnDate |
POST https://DomainName/api/v1/loans/{loanId}?command=withdrawnByApplicant
POST loans/1?command=withdrawnByApplicant
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"withdrawnOnDate": "20 September 2011",
"note": "Reason loan applicant withdrew from application."
}
{
"officeId": 1,
"clientId": 1,
"loanId": 2,
"resourceId": 2,
"changes": {
"status": {
"id": 400,
"code": "loanStatusType.withdrawn.by.client",
"value": "Withdrawn by applicant",
"pendingApproval": false,
"waitingForDisbursal": false,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"withdrawnOnDate": "20 September 2011",
"closedOnDate": "20 September 2011"
}
}
Disburse Loan
Mandatory Fields |
| actualDisbursementDate |
POST https://DomainName/api/v1/loans/{loanId}?command=disburse
POST loans/1?command=disburse
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"actualDisbursementDate": "14 May 2013",
"paymentTypeId": "12",
"note": "",
"accountNumber": "accno123",
"checkNumber": "chec123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 1,
"changes": {
"accountNumber": "accno123",
"checkNumber": "chec123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123",
"status": {
"id": 300,
"code": "loanStatusType.active",
"value": "Active",
"pendingApproval": false,
"waitingForDisbursal": false,
"active": true,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"actualDisbursementDate": "14 May 2013"
}
}
Undo Loan Disbursal
POST https://DomainName/api/v1/loans/{loanId}?command=undoDisbursal
POST loans/1?command=undoDisbursal
Content-Type: application/json
{
"note": "Some comment"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 200,
"code": "loanStatusType.approved",
"value": "Approved",
"pendingApproval": false,
"waitingForDisbursal": true,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": false,
"closedRescheduled": false,
"closed": false,
"overpaid": false
},
"actualDisbursementDate": ""
}
}
Delete a Loan Application
Note: Only loans in "Submitted and awaiting approval" status can be deleted.
DELETE https://DomainName/api/v1/loans/{loanId}
DELETE loans/1
Content-Type: application/json
No Request Body:
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 1
}
Loan Transactions
Capabilities include loan repayment's, interest waivers and the ability to 'adjust' an existing transaction. An 'adjust'ment of a transaction is really a 'reversal' of existing transaction followed by creation of a new transaction with the provided details.
Field Descriptions |
| transactionAmount |
| The amount of the transaction. |
| transactionDate |
| The date of the transaction. |
Retrieve Loan Transaction 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/1/transactions/template?command=repayment
GET https://DomainName/api/v1/loans/{loanId}/transactions/template"
{
"transactionType": {
"id": 2,
"code": "loanTransactionType.repayment",
"value": "Repayment"
},
"date": [
2009,
8,
1
],
"total": {
"currencyCode": "XOF",
"digitsAfterDecimal": 0,
"inMultiplesOf": 0,
"amount": 471,
"defaultName": "CFA Franc BCEAO",
"nameCode": "currency.XOF",
"displaySymbol": "CFA",
"zero": false,
"greaterThanZero": true,
"displaySymbolValue": "471 CFA"
}
}
Make a Repayment
POST https://DomainName/api/v1/loans/{loanId}/transactions?command=repayment
POST loans/5/transactions?command=repayment
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"transactionDate": "14 May 2013",
"transactionAmount": "500.00",
"paymentTypeId": "12",
"note": "check payment",
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 5,
"resourceId": 564,
"changes": {
"transactionDate": "14 May 2013",
"transactionAmount": "500.00",
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"note": "check payment",
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
}
Waive Interest
POST https://DomainName/api/v1/loans/{loanId}/transactions?command=waiveInterest
POST loans/5/transactions?command=waiveInterest
Content-Type: application/json
Request Body:
{
"locale": "en_GB",
"dateFormat": "dd MMMM yyyy",
"transactionDate": "14 May 2012",
"transactionAmount": "400",
"note": "Optional note related to the waiving of interest."
}
{
"officeId": 1,
"clientId": 1,
"loanId": 5,
"resourceId": 5,
"changes": {
"transactionDate": "14 May 2012",
"transactionAmount": "400",
"locale": "en_GB",
"dateFormat": "dd MMMM yyyy",
"note": "Optional note related to the interest waiver."
}
}
Write-off Loan
POST https://DomainName/api/v1/loans/{loanId}/transactions?command=writeoff
POST loans/70/transactions?command=writeoff
Content-Type: application/json
Request Body:
{
"locale": "en_GB",
"dateFormat": "dd MMMM yyyy",
"transactionDate": "14 May 2012",
"note": "Write-off note"
}
{
"officeId": 1,
"clientId": 7,
"loanId": 70,
"resourceId": 442,
"changes": {
"transactionDate": "1 March 2012",
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"status": {
"id": 601,
"code": "loanStatusType.closed.written.off",
"value": "Closed (written off)",
"pendingApproval": false,
"waitingForDisbursal": false,
"active": false,
"closedObligationsMet": false,
"closedWrittenOff": true,
"closedRescheduled": false,
"closed": true,
"overpaid": false
},
"closedOnDate": "1 March 2012",
"writtenOffOnDate": "1 March 2012",
"note": "Write-off note"
}
}
Undo Loan Write-off Transaction
POST https://DomainName/api/v1/loans/{loanId}/transactions?command=undowriteoff
POST loans/70/transactions?command=undowriteoff
Content-Type: application/json
Request Body:
{ }
{
"officeId": 1,
"clientId": 1,
"loanId": 22
}
Retrieve a Transaction Details
Example Request:
loans/5/transactions/3
GET https://DomainName/api/v1/loans/{loanId}/transactions/{transactionId}
{
"id": 3,
"type": {
"id": 2,
"code": "loanTransactionType.repayment",
"value": "Repayment",
"disbursement": false,
"repaymentAtDisbursement": false,
"repayment": true,
"contra": false,
"waiveInterest": false,
"waiveCharges": false,
"writeOff": false,
"recoveryRepayment": false
},
"date": [
2012,
5,
14
],
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 559.88,
"interestPortion": 559.88
}
Adjust a Transaction
Note: there is no need to specify command={transactionType} parameter.
Mandatory Fields |
| transactionDate, transactionAmount |
POST https://DomainName/api/v1/loans/{loanId}/transactions/{transactionId}
POST loans/1/transactions/2
Content-Type: application/json
Request Body:
{
"locale": "en_GB",
"dateFormat": "dd MMMM yyyy",
"transactionDate": "25 May 2012",
"transactionAmount": "50,000.00",
"note": "An optional note about why your adjusting or changing the transaction."
}
{
"resourceId": 16
}
Guarantors
A person who guarantees to pay for someone else's debt if he or she should default on a loan obligation. A guarantor acts as a co-signor of sorts.
Field Descriptions |
| guarantorType |
| Identifies if the guarantor is
an existing Client, Staff member or an external
individual Refer Retrieve Guarantor Details Template for complete details |
| entityId |
| The identifier for guarantors who are an existing Client of Staff member. |
| firstname |
| Guarantors first name |
| lastname |
| Guarantors last name |
| officeName |
| Name of the office with which the internal guarantors are associated |
| addressLine1, addressLine2, city, state, zip, country, mobileNumber, housePhoneNumber, comment, dob |
| Address, contact and date of birth details of an external guarantor |
List Guarantors
Example Requests:
loans/1/guarantors
loans/1/guarantors?fields=firstname,lastname
GET https://DomainName/api/v1/loans/{loanId}/guarantors
[
{
"id": 1,
"loanId": 1,
"guarantorType": {
"id": 1,
"code": "guarantor.existing.customer",
"value": "CUSTOMER"
},
"firstname": "Declan",
"lastname": "Browne",
"officeName": "Head Office",
"joinedDate": [
2009,
1,
4
]
}
]
Retrieve Guarantors 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:
loans/1/guarantors/template
GET https://DomainName/api/v1/loans/{loanId}/guarantors/template
{
"guarantorType": {
"id": 1,
"code": "guarantor.existing.customer",
"value": "CUSTOMER"
},
"guarantorTypeOptions": [
{
"id": 1,
"code": "guarantor.existing.customer",
"value": "CUSTOMER"
},
{
"id": 2,
"code": "guarantor.staff",
"value": "STAFF"
},
{
"id": 3,
"code": "guarantor.external",
"value": "EXTERNAL"
}
]
}
Retrieve a Guarantor
Example Requests:
/loans/1/guarantors/1
/loans/1/guarantors/1
/loans/1/guarantors/1?fields=firstname
GET https://DomainName/api/v1/loans/{loanId}/guarantors/{guarantorId}
{
"id": 1,
"loanId": 1,
"guarantorType": {
"id": 1,
"code": "guarantor.existing.customer",
"value": "CUSTOMER"
},
"firstname": "Declan",
"officeName": "Head Office",
"joinedDate": [
2009,
1,
4
]
}
Create a Guarantor
Note: You may associate any number of Guarantors
to a Loan. The mandatory fields would vary based
on the "guarantorType"
Mandatory Fields
for "internal" guarantors |
| guarantorTypeId, entityId |
Mandatory Fields for "external" guarantors |
| guarantorTypeId, firstname, lastname |
POST https://DomainName/api/v1//loans/{loanId}}/guarantors
POST /loans/1/guarantors
Content-Type: application/json
Request Body:
{
guarantorTypeId:3,
firstname:Lyndon,
lastname:Johnson
}
{
"officeId": 2,
"loanId": 1,
"resourceId": 9
}
POST /loans/1/guarantors
Content-Type: application/json
Request Body:
{
guarantorTypeId:1,
entityId:2
}
{
"officeId": 2,
"loanId": 1,
"resourceId": 10
}
Update a Guarantor
PUT https://DomainName/api/v1/loans/{loanId}/guarantors/{guarantorId}
PUT loans/1/guarantors/1
Content-Type: application/json
Request Body:
{
entityId:1
}
{
"officeId": 1,
"resourceId": 1,
"changes": {
"entityId": 1
}
}
Remove a Guarantor
Note: A guarantor can be removed only from loans that are not yet approved.
DELETE https://DomainName/api/v1/loans/{loanId}/guarantors/{guarantorId}
DELETE loans/1/guarantors/1
Content-Type: application/json
No Request Body:
{
"officeId": 2,
"loanId": 1,
"resourceId": 1
}
Loan Collateral
In lending agreements, collateral is a borrower's pledge of specific property to a lender, to secure repayment of a loan. The collateral serves as protection for a lender against a borrower's default - that is, any borrower failing to pay the principal and interest under the terms of a loan obligation. If a borrower does default on a loan (due to insolvency or other event), that borrower forfeits (gives up) the property pledged as collateral - and the lender then becomes the owner of the collateral
Field Descriptions |
| type |
| Identifies the type of a collateral Ex: Gold, property etc (permitted types can be configured using Code Values for the Code LoanCollateral) Refer Retrieve Collateral Details Template for complete details |
| value |
| The market value of a Collateral. |
| description |
| Description for the collateral |
| currency |
| Details of the currency used to estimate the value of a Collateral. The currency defaults to the currency of the Loan for which this Collateral serves as a guarantee |
List Loan Collaterals
Example Requests:
loans/1/collaterals
loans/1/collaterals?fields=value,description
GET https://DomainName/api/v1/loans/{loanId}/collaterals
[
{
"id": 12,
"type": {
"id": 8,
"name": "Gold"
},
"value": 50000,
"description": "24 Carat Gold chain weighing 12 grams",
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
}
]
Retrieve Collateral 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:
loans/1/collaterals/template
GET https://DomainName/api/v1/loans/{loanId}/collaterals/template
{
"allowedCollateralTypes": [
{
"id": 9,
"name": "Silver",
"position": 0
},
{
"id": 8,
"name": "Gold",
"position": 0
},
{
"id": 10,
"name": "Property",
"position": 0
}
]
}
Retrieve a Collateral
Example Requests:
/loans/1/collaterals/1
/loans/1/collaterals/1?fields=value,description
GET https://DomainName/api/v1/loans/{loanId}/collaterals/{guarantorId}
{
"id": 12,
"type": {
"id": 8,
"name": "Gold"
},
"value": 50000,
"description": "24 Carat Gold chain weighing 12 grams",
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
}
Create a Collateral
Note: Currently, Collaterals may be added only before a Loan
is approved
Mandatory Fields
for "internal" collaterals |
| collateralTypeId |
POST https://DomainName/api/v1//loans/{loanId}/collaterals
POST /loans/1/collaterals
Content-Type: application/json
Request Body:
{
collateralTypeId:9,
}
{
"loanId": 1,
"resourceId": 12
}
POST /loans/1/collaterals
Content-Type: application/json
Request Body:
{
"collateralTypeId":"8",
"value": "50000",
"dateFormat":"dd MMMM yyyy",
"locale": "en",
"description": "24 Carat Gold chain weighing 12 grams"
}
{
"loanId": 1,
"resourceId": 13
}
Update a Collateral
PUT https://DomainName/api/v1/loans/{loanId}/collaterals/{collateralId}
PUT loans/1/collaterals/12
Content-Type: application/json
Request Body:
{
"description": "22 Carat Gold chain weighing 12 grams"
}
{
"loanId": 1,
"resourceId": 12,
"changes": {
"description": "22 Carat Gold chain weighing 12 grams"
}
}
Remove a Collateral
Note: A collateral can only be removed from Loans that are not yet approved.
DELETE https://DomainName/api/v1/loans/{loanId}/collaterals/{collateralId}
DELETE loans/1/collaterals/13
Content-Type: application/json
No Request Body:
{
"loanId": 1,
"resourceId": 13
}
Loan Charges
Its typical for MFIs to add extra costs for their loan products. They can be either Fees or Penalties.
Loan Charges are instances of Charges and represent either fees and penalties for loan products. Refer Charges for documentation of the various properties of a charge, Only additional properties ( specific to the context of a Charge being associated with a Loan) are described here
Field Descriptions |
| amountPaid |
| The Total amount which has been paid for this Charge |
| amountWaived |
| The Total amount that has been waived for this Charge |
| amountWrittenOff |
| Total amount written off from this Charge |
| amountOutstanding |
| The Total outstanding amount for this Charge |
List Loan Charges
Example Requests:
loans/1/charges
loans/1/charges?fields=name,amountOrPercentage
GET https://DomainName/api/v1/loans/{loanId}/charges
[
{
"id": 1,
"chargeId": 1,
"name": "Loan Processing fee",
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"percentage": 0,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 100,
"amountOrPercentage": 100,
"penalty": false
},
{
"id": 7,
"chargeId": 2,
"name": "Collection Fee",
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"dueDate": [
2013,
3,
29
],
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"percentage": 0,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 100,
"amountOrPercentage": 100,
"penalty": false
}
]
Retrieve Loan Charges 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:
loans/1/charges/template
GET https://DomainName/api/v1/loans/{loanId}/charges/template
{
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"chargeOptions": [
{
"id": 2,
"name": "Collection Fee",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
}
},
{
"id": 3,
"name": "Late payment penalty",
"active": true,
"penalty": true,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 1,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
}
},
{
"id": 1,
"name": "Loan Processing fee",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
}
}
],
"penalty": false
}
Retrieve a Loan Charge
Example Requests:
/loans/1/charges/1
/loans/1/charges/1?fields=name,amountOrPercentage
GET https://DomainName/api/v1/loans/{loanId}/charges/{chargeId}
{
"id": 1,
"chargeId": 1,
"name": "Loan Processing fee",
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"percentage": 0,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 100,
"amountOrPercentage": 100,
"penalty": false
}
Create a Loan Charge
Mandatory Fields
for Loan Charges |
| chargeId, amount, dueDate |
POST https://DomainName/api/v1/loans/{loanId}/charges
POST /loans/1/charges
Content-Type: application/json
Request Body:
{
"chargeId": "2",
"locale": "en",
"amount": "100",
"dateFormat": "dd MMMM yyyy",
"dueDate": "29 April 2013"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 31
}
Update a Loan Charge
Currently Loan Charges may be updated only if the Loan is not yet approved
PUT https://DomainName/api/v1/loans/{loanId}/charges/{chargeId}
PUT loans/1/charges/12
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"amount": "60",
"dueDate": "27 March 2013"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 6,
"changes": {
"dueDate": "27 March 2013",
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"amount": 60.0
}
}
Pay Loan Charge
Loan Charge will be paid if the loan is linked with a savings account
POST https://DomainName/api/v1/loans/{loanId}/charges/{chargeId}?command=pay
POST loans/1/charges/12?command=pay
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"transactionDate": "19 September 2013"
}
{
"officeId": 1,
"clientId": 1,
"loanId": 6,
"savingsId": 1,
"resourceId": 12
}
Delete a Loan Charge
Note:Currently, A Loan Charge may only be removed from Loans that are not yet approved.
DELETE https://DomainName/api/v1/loans/{loanId}/charges/{chargeId}
DELETE loans/1/charges/2
Content-Type: application/json
No Request Body:
{
"officeId": 1,
"clientId": 1,
"loanId": 1,
"resourceId": 2
}
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://DomainName/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://DomainName/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://DomainName/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://DomainName/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://DomainName/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 |
| name |
| Name associated with loan product on system. |
| description |
| For providing helpful description of product offering. |
| fundId |
| For associating a loan product with a given fund by default. |
| includeInBorrowerCycle |
| It is a flag, Used to denote whether the loans should include in loan cycle counter or not. |
| useBorrowerCycle |
| It is a flag, Used to denote whether the loans should depend on borrower loan cycle counter or not. |
| currencyCode |
| A three letter ISO code of currency. |
| digitsAfterDecimal |
| Override the currency default value for digitsAfterDecimal. |
| inMultiplesOf |
| Override the default value for rounding currency to multiples of value provided. |
| principal |
| The loan amount to be disbursed to through loan. |
| numberOfRepayments |
| Number of installments to repay. Used like: numberOfRepayments Every repaymentEvery repaymentFrequencyType e.g. 10 (repayments) Every 12 Weeks |
| repaymentEvery |
| Used like: numberOfRepayments Every
repaymentEvery repaymentFrequencyType e.g. 10 (repayments) Every 12 Weeks |
| repaymentFrequencyType |
| Used like: numberOfRepayments Every
repaymentEvery repaymentFrequencyType e.g. 10 (repayments) Every 12 Weeks Example Values: 0=Days, 1=Weeks, 2=Months |
| interestRatePerPeriod |
| Interest Rate. Used like: interestRatePerPeriod % interestRateFrequencyType - interestType e.g. 12.0000% Per year - Declining Balance |
| interestRateFrequencyType |
| Used like: interestRatePerPeriod%
interestRateFrequencyType - interestType e.g. 12.0000% Per year - Declining Balance Example Values: 2=Per month, 3=Per year |
| amortizationType |
| Example Values: 0=Equal principle payments, 1=Equal installments |
| interestType |
| Used like: interestRatePerPeriod%
interestRateFrequencyType - interestType e.g. 12.0000% Per year - Declining Balance Example Values: 0=Declining Balance, 1=Flat |
| interestCalculationPeriodType |
| Example Values: 0=Daily, 1=Same as repayment period |
| 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. |
| principalVariationsForBorrowerCycle,interestRateVariationsForBorrowerCycle, numberOfRepaymentVariationsForBorrowerCycle |
| Variations for loan, based on borrower cycle number |
| transactionProcessingStrategyId |
|
An enumeration that indicates the type of transaction processing strategy to be used. This relates to functionality that is also known as Payment Application Logic.
A number of out of the box appraches exist, some are custom to specific MFIs, some are more general and indicate the order in which payments are processed. Refer to the Payment Application Logic / Transaction Processing Strategy section in the appendix for more detailed overview of each available payment application logic provided out of the box. List of current approaches:
|
| graceOnPrincipalPayment |
| Optional: Integer - represents the number of repayment periods that grace should apply to the principal component of a repayment period. |
| graceOnInterestPayment |
| Optional: Integer - represents the number of repayment periods that grace should apply to the interest component of a repayment period. Interest is still calculated but offset to later repayment periods. |
| graceOnInterestCharged |
| Optional: Integer - represents the number of repayment periods that should be interest-free. |
| accountingRule |
| Specifies if accounting is enabled for the particular product and the type of the accounting rule to be used Example Values:1=NONE,2=CASH_BASED, 3=ACCRUAL_BASED |
List Loan Products
Example Requests:
loanproducts
loanproducts?fields=name,description,interestRateFrequencyType,amortizationType
GET https://DomainName/api/v1/loanproducts
[
{
"id": 1,
"name": "personal loan product",
"includeInBorrowerCycle": false,
"useBorrowerCycle": false,
"startDate": [
2013,
9,
2
],
"closeDate": [
2014,
2,
7
],
"status": "loanProduct.active",
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"inMultiplesOf": 0,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"principal": 10000.000000,
"minPrincipal": 5000.000000,
"maxPrincipal": 15000.000000,
"numberOfRepayments": 10,
"minNumberOfRepayments": 5,
"maxNumberOfRepayments": 15,
"repaymentEvery": 7,
"repaymentFrequencyType": {
"id": 0,
"code": "repaymentFrequency.periodFrequencyType.days",
"value": "Days"
},
"interestRatePerPeriod": 15.000000,
"interestRateFrequencyType": {
"id": 3,
"code": "interestRateFrequency.periodFrequencyType.years",
"value": "Per year"
},
"annualInterestRate": 15.000000,
"amortizationType": {
"id": 1,
"code": "amortizationType.equal.installments",
"value": "Equal installments"
},
"interestType": {
"id": 1,
"code": "interestType.flat",
"value": "Flat"
},
"interestCalculationPeriodType": {
"id": 1,
"code": "interestCalculationPeriodType.same.as.repayment.period",
"value": "Same as repayment period"
},
"transactionProcessingStrategyId": 1,
"transactionProcessingStrategyName": "Mifos style",
"principalVariationsForBorrowerCycle": [],
"interestRateVariationsForBorrowerCycle": [],
"numberOfRepaymentVariationsForBorrowerCycle": [],
"accountingRule": {
"id": 2,
"code": "accountingRuleType.cash",
"value": "CASH BASED"
}
}
]
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://DomainName/api/v1/loanproducts/template
{
"includeInBorrowerCycle": false,
"useBorrowerCycle": false,
"currency": {
"code": "",
"name": "",
"decimalPlaces": 0,
"inMultiplesOf": 0,
"displaySymbol": "",
"nameCode": "",
"displayLabel": " []"
},
"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"
},
"principalVariationsForBorrowerCycle": [],
"interestRateVariationsForBorrowerCycle": [],
"numberOfRepaymentVariationsForBorrowerCycle": [],
"accountingRule": {
"id": 1,
"code": "accountingRuleType.none",
"value": "NONE"
},
"paymentTypeOptions": [
{
"id": 10,
"name": "check",
"position": 1
}
],
"currencyOptions": [
{
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
],
"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"
}
],
"amortizationTypeOptions": [
{
"id": 1,
"code": "amortizationType.equal.installments",
"value": "Equal installments"
},
{
"id": 0,
"code": "amortizationType.equal.principal",
"value": "Equal principal 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"
}
],
"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)"
},
{
"id": 5,
"code": "principal-interest-penalties-fees-order-strategy",
"name": "Principal Interest Penalties Fees Order"
},
{
"id": 6,
"code": "interest-principal-penalties-fees-order-strategy",
"name": "Interest Principal Penalties Fees Order"
}
],
"chargeOptions": [
{
"id": 5,
"name": "des charge",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100.000000,
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 1,
"name": "flat install",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 50.000000,
"chargeTimeType": {
"id": 8,
"code": "chargeTimeType.instalmentFee",
"value": "Instalment Fee"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 9,
"name": "install amt+int",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 5.000000,
"chargeTimeType": {
"id": 8,
"code": "chargeTimeType.instalmentFee",
"value": "Instalment Fee"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 3,
"code": "chargeCalculationType.percent.of.amount.and.interest",
"value": "% Loan Amount + Interest"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 10,
"name": "install int",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 5.000000,
"chargeTimeType": {
"id": 8,
"code": "chargeTimeType.instalmentFee",
"value": "Instalment Fee"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 4,
"code": "chargeCalculationType.percent.of.interest",
"value": "% Interest"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 2,
"name": "install per",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 5.000000,
"chargeTimeType": {
"id": 8,
"code": "chargeTimeType.instalmentFee",
"value": "Instalment Fee"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
},
"chargePaymentMode": {
"id": 1,
"code": "chargepaymentmode.accounttransfer",
"value": "Account transfer"
}
},
{
"id": 8,
"name": "spe int",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 5.000000,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 4,
"code": "chargeCalculationType.percent.of.interest",
"value": "% Interest"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 4,
"name": "specific acc transfer",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100.000000,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 1,
"code": "chargepaymentmode.accounttransfer",
"value": "Account transfer"
}
},
{
"id": 7,
"name": "specific amt+int",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 5.000000,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 3,
"code": "chargeCalculationType.percent.of.amount.and.interest",
"value": "% Loan Amount + Interest"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 3,
"name": "specific per",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 5.000000,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 6,
"name": "xyz",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 50.000000,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 1,
"code": "chargepaymentmode.accounttransfer",
"value": "Account transfer"
}
}
],
"accountingRuleOptions": [
{
"id": 1,
"code": "accountingRuleType.none",
"value": "NONE"
},
{
"id": 2,
"code": "accountingRuleType.cash",
"value": "CASH BASED"
},
{
"id": 3,
"code": "accountingRuleType.accrual",
"value": "ACCRUAL BASED"
}
],
"accountingMappingOptions": {
"liabilityAccountOptions": [
{
"id": 11,
"name": "over payment",
"glCode": "13",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 2,
"code": "accountType.liability",
"value": "LIABILITY"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "over payment",
"tagId": {
"id": 0
},
"organizationRunningBalance": 0
},
],
"assetAccountOptions": [
{
"id": 1,
"name": "fund source",
"glCode": "01",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "fund source",
"tagId": {
"id": 0
},
"organizationRunningBalance": -60000
},
{
"id": 2,
"name": "Loan portfolio",
"glCode": "02",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "Loan portfolio",
"tagId": {
"id": 0
},
"organizationRunningBalance": 60000
},
{
"id": 3,
"name": "transfers",
"glCode": "03",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "transfers",
"tagId": {
"id": 0
},
"organizationRunningBalance": 0
},
],
"expenseAccountOptions": [
{
"id": 10,
"name": "loans written off 2",
"glCode": "12",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 5,
"code": "accountType.expense",
"value": "EXPENSE"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "loans written off 2",
"tagId": {
"id": 0
},
"organizationRunningBalance": 0
}
],
"incomeAccountOptions": [
{
"id": 4,
"name": "income from interest",
"glCode": "04",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "income from interest",
"tagId": {
"id": 0
},
"organizationRunningBalance": 19
},
{
"id": 8,
"name": "income from fees 2",
"glCode": "10",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "income from fees 2",
"tagId": {
"id": 0
},
"organizationRunningBalance": 0
},
{
"id": 9,
"name": "income from penalities 2",
"glCode": "11",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "income from penalities 2",
"tagId": {
"id": 0
},
"organizationRunningBalance": 0
}
]
},
"valueConditionTypeOptions": [
{
"id": 2,
"code": "LoanProductValueConditionType.equal",
"value": "equals"
},
{
"id": 3,
"code": "LoanProductValueConditionType.greterthan",
"value": "greter than"
}
]
}
Retrieve a Loan Product
Example Requests:
loanproducts/1
loanproducts/1?template=true
loanproducts/1?fields=name,description,numberOfRepayments
GET https://DomainName/api/v1/loanproducts/{productId}
{
"id": 11,
"name": "advanced accounting",
"includeInBorrowerCycle": true,
"useBorrowerCycle": true,
"status": "loanProduct.active",
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"inMultiplesOf": 0,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"principal": 10000.000000,
"minPrincipal": 2000.000000,
"maxPrincipal": 15000.000000,
"numberOfRepayments": 7,
"repaymentEvery": 7,
"repaymentFrequencyType": {
"id": 0,
"code": "repaymentFrequency.periodFrequencyType.days",
"value": "Days"
},
"interestRatePerPeriod": 5.000000,
"interestRateFrequencyType": {
"id": 2,
"code": "interestRateFrequency.periodFrequencyType.months",
"value": "Per month"
},
"annualInterestRate": 60.000000,
"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"
},
"transactionProcessingStrategyId": 1,
"transactionProcessingStrategyName": "Mifos style",
"charges": [],
"principalVariationsForBorrowerCycle": [
{
"id": 21,
"borrowerCycleNumber": 1,
"paramType": {
"id": 1,
"code": "LoanProductParamType.principal",
"value": "principal"
},
"valueConditionType": {
"id": 2,
"code": "LoanProductValueConditionType.equal",
"value": "equals"
},
"minValue": 2000.000000,
"maxValue": 20000.000000,
"defaultValue": 15000.000000
},
{
"id": 20,
"borrowerCycleNumber": 1,
"paramType": {
"id": 1,
"code": "LoanProductParamType.principal",
"value": "principal"
},
"valueConditionType": {
"id": 3,
"code": "LoanProductValueConditionType.greterthan",
"value": "greter than"
},
"minValue": 3000.000000,
"maxValue": 25000.000000,
"defaultValue": 20000.000000
}
],
"interestRateVariationsForBorrowerCycle": [],
"numberOfRepaymentVariationsForBorrowerCycle": [],
"accountingRule": {
"id": 2,
"code": "accountingRuleType.cash",
"value": "CASH BASED"
},
"accountingMappings": {
"fundSourceAccount": {
"id": 1,
"name": "fund source",
"glCode": "01"
},
"loanPortfolioAccount": {
"id": 2,
"name": "Loan portfolio",
"glCode": "02"
},
"transfersInSuspenseAccount": {
"id": 3,
"name": "transfers",
"glCode": "03"
},
"interestOnLoanAccount": {
"id": 4,
"name": "income from interest",
"glCode": "04"
},
"incomeFromFeeAccount": {
"id": 8,
"name": "income from fees 2",
"glCode": "10"
},
"incomeFromPenaltyAccount": {
"id": 9,
"name": "income from penalities 2",
"glCode": "11"
},
"writeOffAccount": {
"id": 10,
"name": "loans written off 2",
"glCode": "12"
},
"overpaymentLiabilityAccount": {
"id": 11,
"name": "over payment",
"glCode": "13"
}
},
"paymentChannelToFundSourceMappings": [
{
"paymentType": {
"id": 10,
"name": "check"
},
"fundSourceAccount": {
"id": 1,
"name": "fund source",
"glCode": "01"
}
}
],
"feeToIncomeAccountMappings": [
{
"charge": {
"id": 1,
"name": "flat install",
"active": false,
"penalty": false
},
"incomeAccount": {
"id": 8,
"name": "income from fees 2",
"glCode": "10"
}
},
{
"charge": {
"id": 2,
"name": "install per",
"active": false,
"penalty": false
},
"incomeAccount": {
"id": 4,
"name": "income from interest",
"glCode": "04"
}
},
{
"charge": {
"id": 5,
"name": "des charge",
"active": false,
"penalty": false
},
"incomeAccount": {
"id": 9,
"name": "income from penalities 2",
"glCode": "11"
}
}
]
}
Create a Loan Product
Depending of the Accounting Rule (accountingRule) selected, additional fields with details of the appropriate Ledger Account identifiers would need to be passed in.
Refer MifosX Accounting Specs Draft for more details regarding the significance of the selected accounting ruleMandatory Fields |
| name, currencyCode, digitsAfterDecimal, inMultiplesOf, principal, numberOfRepayments, repaymentEvery, repaymentFrequencyType, interestRatePerPeriod, interestRateFrequencyType, amortizationType, interestType, interestCalculationPeriodType, transactionProcessingStrategyId, accountingRule |
Optional Fields |
| inArrearsTolerance, graceOnPrincipalPayment, graceOnInterestPayment, graceOnInterestCharged, charges, paymentChannelToFundSourceMappings, feeToIncomeAccountMappings, penaltyToIncomeAccountMappings, includeInBorrowerCycle, useBorrowerCycle,principalVariationsForBorrowerCycle, numberOfRepaymentVariationsForBorrowerCycle, interestRateVariationsForBorrowerCycle |
Additional Mandatory Fields for Cash(2) based accounting |
| fundSourceAccountId, loanPortfolioAccountId, interestOnLoanAccountId, incomeFromFeeAccountId, incomeFromPenaltyAccountId, writeOffAccountId, transfersInSuspenseAccountId, overpaymentLiabilityAccountId |
Additional Mandatory Fields for Accrual(3) based accounting |
| fundSourceAccountId, loanPortfolioAccountId, interestOnLoanAccountId, incomeFromFeeAccountId, incomeFromPenaltyAccountId, writeOffAccountId, receivableInterestAccountId, receivableFeeAccountId, receivablePenaltyAccountId, transfersInSuspenseAccountId, overpaymentLiabilityAccountId |
POST https://DomainName/api/v1/loanproducts
POST loanproducts
Content-Type: application/json
Request Body:
{"currencyCode":"USD",
"includeInBorrowerCycle":"true",
"useBorrowerCycle":true,
"digitsAfterDecimal":"2",
"inMultiplesOf":"0",
"repaymentFrequencyType":0,
"interestRateFrequencyType":2,
"amortizationType":1,
"interestType":0,
"interestCalculationPeriodType":1,
"transactionProcessingStrategyId":1,
"principalVariationsForBorrowerCycle":[],
"interestRateVariationsForBorrowerCycle":[],
"numberOfRepaymentVariationsForBorrowerCycle":[
{
"valueConditionType":2,
"borrowerCycleNumber":"1",
"minValue":"5",
"defaultValue":"10",
"maxValue":"15"
},
{
"valueConditionType":3,
"borrowerCycleNumber":"1",
"minValue":"7",
"defaultValue":"15",
"maxValue":"20"
}
],
"accountingRule":"2",
"name":"product 5",
"principal":"5000",
"numberOfRepayments":"7",
"repaymentEvery":"7",
"interestRatePerPeriod":"5",
"paymentChannelToFundSourceMappings":[],
"feeToIncomeAccountMappings":[],
"penaltyToIncomeAccountMappings":[],
"charges":[],
"dateFormat":"dd MMMM yyyy",
"locale":"en",
"fundSourceAccountId":1,
"loanPortfolioAccountId":2,
"transfersInSuspenseAccountId":3,
"interestOnLoanAccountId":4,
"incomeFromFeeAccountId":8,
"incomeFromPenaltyAccountId":9,
"writeOffAccountId":10,
"overpaymentLiabilityAccountId":11
}
{
"resourceId": 1
}
POST loanproducts
Content-Type: application/json
Request Body:
{
"name": "LP Cash Accounting",
"currencyCode": "USD",
"locale": "en_GB",
"digitsAfterDecimal": "2",
"inMultiplesOf": 0,
"principal": "100,000.00",
"numberOfRepayments": "12",
"repaymentEvery": "1",
"repaymentFrequencyType": 2,
"transactionProcessingStrategyId": 1,
"interestRatePerPeriod": "1.75",
"interestRateFrequencyType": 2,
"amortizationType": 1,
"interestType": 0,
"interestCalculationPeriodType": 1,
"accountingRule":"2",
"fundSourceAccountId":"4",
"loanPortfolioAccountId":"8",
"interestOnLoanAccountId":"34",
"incomeFromFeeAccountId":"37",
"incomeFromPenaltyAccountId":"35",
"writeOffAccountId":"41",
"transfersInSuspenseAccountId":"4",
"overpaymentLiabilityAccountId":"2",
"paymentChannelToFundSourceMappings": [
{
"paymentTypeId": "11",
"fundSourceAccountId": "11"
}
],
"feeToIncomeAccountMappings": [
{
"chargeId": "1",
"incomeAccountId": "5"
},
{
"chargeId": "2",
"incomeAccountId": "8"
}
],
"penaltyToIncomeAccountMappings": [
{
"chargeId": "6",
"incomeAccountId": "9"
}
]
}
{
"resourceId": 2
}
POST loanproducts
Content-Type: application/json
Request Body:
{
"name": "LP Accrual Accounting",
"currencyCode": "USD",
"locale": "en_GB",
"digitsAfterDecimal": "2",
"inMultiplesOf": 0,
"principal": "100,000.00",
"numberOfRepayments": "12",
"repaymentEvery": "1",
"repaymentFrequencyType": 2,
"transactionProcessingStrategyId": 1,
"interestRatePerPeriod": "1.75",
"interestRateFrequencyType": 2,
"amortizationType": 1,
"interestType": 0,
"interestCalculationPeriodType": 1,
"accountingRule":"3",
"fundSourceAccountId":"4",
"loanPortfolioAccountId":"8",
"receivableInterestAccountId":"9",
"receivableFeeAccountId":"11",
"receivablePenaltyAccountId":"10",
"interestOnLoanAccountId":"34",
"incomeFromFeeAccountId":"37",
"incomeFromPenaltyAccountId":"35",
"overpaymentLiabilityAccountId":"2",
"writeOffAccountId":"41"
}
{
"resourceId": 3
}
Update a Loan Product
PUT https://DomainName/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"
}
}
Loan Products Mix
If you have the appropriate permissions, you can decide which types of products a given client or group can mix. In this way, you can restrict clients from having active loans accounts of different products at the same time.
Field Descriptions |
| restrictedProducts |
| List of productIds to create a product mix |
List Loan Product Mix
Example Requests:
loanproducts?associations=productMixes
GET https://DomainName/api/v1/loanproducts?associations=productMixes
[
{
"productId": 1,
"productName": "Personal Loan",
"restrictedProducts": [
{
"id": 2,
"name": "Joint Loan",
"includeInBorrowerCycle": false
},
{
"id": 5,
"name": "Primary Loan",
"includeInBorrowerCycle": false
},
{
"id": 3,
"name": "Daily Loan",
"includeInBorrowerCycle": false
}
],
"allowedProducts": [
{
"id": 1,
"name": "Personal Loan",
"includeInBorrowerCycle": false
},
{
"id": 6,
"name": "Personal Loan -2",
"includeInBorrowerCycle": false
},
{
"id": 4,
"name": "Weekly Loan",
"includeInBorrowerCycle": false
}
]
},
{
"productId": 2,
"productName": "Joint Loan",
"restrictedProducts": [
{
"id": 1,
"name": "Personal Loan",
"includeInBorrowerCycle": false
},
{
"id": 6,
"name": "Personal Loan -2",
"includeInBorrowerCycle": false
}
],
"allowedProducts": [
{
"id": 3,
"name": "Daily Loan",
"includeInBorrowerCycle": false
},
{
"id": 2,
"name": "Joint Loan",
"includeInBorrowerCycle": false
},
{
"id": 5,
"name": "Primary Loan",
"includeInBorrowerCycle": false
},
{
"id": 4,
"name": "Weekly Loan",
"includeInBorrowerCycle": false
}
]
}
]
Retrieve Product Mix 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:
This request gets all the products details for which productmix is not defined.
loanproducts/template?isProductMixTemplate=true
This request gets the productmix details for the specific loanproduct.
loanproducts/5/productmix
loanproducts/5/productmix?template=true
GET https://DomainName/api/v1/loanproducts/template?isProductMixTemplate=true
{
"productOptions": [
{
"id": 5,
"name": "Primary Loan"
},
{
"id": 4,
"name": "Weekly Loan"
}
]
}
GET https://DomainName/api/v1/loanproducts/5/productmix
{
"restrictedProducts": [
{
"id": 1,
"name": "Personal Loan",
"includeInBorrowerCycle": false
}
],
"allowedProducts": [
{
"id": 3,
"name": "Daily Loan",
"includeInBorrowerCycle": false
},
{
"id": 2,
"name": "Joint Loan",
"includeInBorrowerCycle": false
},
{
"id": 6,
"name": "Personal Loan -2",
"includeInBorrowerCycle": false
},
{
"id": 5,
"name": "Primary Loan",
"includeInBorrowerCycle": false
},
{
"id": 4,
"name": "Weekly Loan",
"includeInBorrowerCycle": false
}
]
}
Retrieve Loan Product Mix
Example Requests:
loanproducts/5/productmix
GET https://DomainName/api/v1/loanproducts/5/productmix
{
"restrictedProducts": [
{
"id": 1,
"name": "Personal Loan",
"includeInBorrowerCycle": false
}
],
"allowedProducts": [
{
"id": 3,
"name": "Daily Loan",
"includeInBorrowerCycle": false
},
{
"id": 2,
"name": "Joint Loan",
"includeInBorrowerCycle": false
},
{
"id": 6,
"name": "Personal Loan -2",
"includeInBorrowerCycle": false
},
{
"id": 5,
"name": "Primary Loan",
"includeInBorrowerCycle": false
},
{
"id": 4,
"name": "Weekly Loan",
"includeInBorrowerCycle": false
}
]
}
Create a Loan Product Mix
Mandatory Fields |
| restrictedProducts |
POST https://DomainName/api/v1/loanproducts/5/productmix
POST loanproducts/{productId}/productmix
Content-Type: application/json
Request Body:
{"restrictedProducts":["1"]}
{
"changes":{
"restrictedProductsForMix":[1],
"removedProductsForMix":[]
},
"productId":5
}
Update a Loan Product Mix
PUT https://DomainName/api/v1/loanproducts/{productId}/productmix
PUT loanproducts/5/productmix
Content-Type: application/json
Request Body:
{
"restrictedProducts":["3"]
}
{
"changes": {
"restrictedProductsForMix": [3],
"removedProductsForMix": [1]
},
"productId": 5
}
Delete a Loan Product Mix
DELETE https://DomainName/api/v1/loanproducts/{productId}/productmix
DELETE loanproducts/5/productmix
{
"changes": {
"removedProductsForMix": [3]
},
"productId": 5
}
Holidays
Some MFI's span large regions where different branch offices might observe different holidays. They need the ability to define holidays for specific branch offices and be able to set the repayment rule to follow during those holidays.
The reschedule of repayments to repaymentsRescheduledTo date during defined holidays is turned on/off by enabling/disabling reschedule-repayments-on-holidays in Global configurations.
Allow Repayment transactions on a defined holidays is turned on/off by enabling/disabling allow-transactions-on-holiday in Global configurations.
Field Descriptions |
| name |
| Name of the holiday. |
| fromDate |
| The date on holiday begins. |
| toDate |
| The date on holiday ends. |
| repaymentsRescheduledTo |
| Date to which repayments will be rescheduled when repayments date falls on a defined holiday. e.g. A holiday is defined on 25th of October 2013 with repaymentsRescheduledTo date to 26th of October 2013 and any loans with repayments date on 25th of October 2013 will be rescheduled to 26th of October 2013. |
| officeId |
| The officeId represents the office to which holiday is applied. |
List Holidays
Example Requests:
holidays?officeId=1
GET https://DomainName/api/v1/holidays?officeId=1
[
{
"id": 1,
"name": "Good Friday",
"fromDate": [
2013,
10,
25
],
"toDate": [
2013,
10,
25
],
"repaymentsScheduleTo": [
2013,
10,
26
],
"status": {
"id": 100,
"code": "holidayStatusType.pending.for.activation",
"value": "Pending for activation"
}
}
]
Create a Holiday
Mandatory Fields |
| name, description, fromDate, toDate, repaymentsRescheduledTo, offices |
POST https://DomainName/api/v1/holidays
POST holidays
Content-Type: application/json
Request Body:
{
"name": "Good Friday",
"description": "Good Friday",
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"fromDate": "25 October 2013",
"toDate": "25 October 2013",
"repaymentsRescheduledTo": "26 October 2013",
"offices": [
{"officeId":"1"},
{"officeId":"2"}
]
}
{
"resourceId": 1
}
Activate a Holiday
Always Holidays are created in pending state. This API allows to activate a holiday.
Only the active holidays are considered for rescheduling the loan repayment.
POST https://DomainName/api/v1/holidays/{holidayId}?command=activate
POST holidays
Content-Type: application/json
Request Body:
{
}
{
"resourceId": 1
}
Retrieve a Holiday
Example Requests:
holidays/1
GET https://DomainName/api/v1/holidays/{holidayId}
{
"id": 1,
"name": "Good Friday",
"fromDate": [
2013,
10,
25
],
"toDate": [
2013,
10,
25
],
"repaymentsRescheduledTo": [
2013,
10,
26
],
"status": {
"id": 100,
"code": "holidayStatusType.active",
"value": "Active"
}
}
Update a Holiday
If a holiday is in pending state (created and not activated) then all fields are allowed to modify. Once holidays become active only name and descriptions are allowed to modify.
PUT https://DomainName/api/v1/holidays/{holidayId}
PUT holidays/1
Content-Type: application/json
Request Body:
{
name:"Independence day",
description: "Holiday for Independence day celebration"
}
{
"resourceId": 1,
"changes": {
"name": "Independence day",
"description": "Holiday for Independence day celebration"
}
}
Delete a Holiday
This API allows to delete a holiday. This is a soft delete the deleted holiday status is marked as deleted.
DELETE https://DomainName/api/v1/holidays/{holidayId}
DELETE holidays/1
Content-Type: application/json
Request Body:
{
}
{
"resourceId": 1
}
Working days
The days of the week that are workdays.
Rescheduling of repayments when it falls on a non-working is turned on /off by enable/disable reschedule-future-repayments parameter in Global configurations.
Allow transactions on non-working days is configurable by enabling/disbaling the allow-transactions-on-non_workingday parameter in Global configurations.
Schedule for repayments on non-working day |
| Same day |
| The repayments schedule for same day regardless of it's a non-working day. |
| Next workday |
| The repayments reschedule to next working day. e.g. if a repayment falls on a non-working day will be rescheduled to next available working day. |
| Previous workday |
| The repayments reschedule to previous working day. e.g. if a repayment falls on a non-working day will be rescheduled to previous available working day. |
| Next scheduled meeting |
| The repayments reschduled to next scheduled meeting. |
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://DomainName/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://DomainName/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:
- maker-checker - defaults to false - if true turns on maker-checker functionality
- reschedule-future-repayments - defaults to false - if true reschedules repayemnts which falls on a non-working day to configured repayment rescheduling rule
- allow-transactions-on-non_workingday - defaults to false - if true allows transactions on non-working days
- reschedule-repayments-on-holidays - defaults to false - if true reschedules repayemnts which falls on a non-working day to defined reschedule date
- allow-transactions-on-holiday - defaults to false - if true allows transactions on holidays
Retrieve Global Configuration
Returns the list global enable/disable configurations.
Example Requests:
configurations
GET https://DomainName/api/v1/configurations
{
"globalConfiguration": [
{
"name": "maker-checker",
"enabled": false
}
]
}
Update Global Configuration
Updates an enable/disable global configuration item.
PUT https://DomainName/api/v1/configurations?maker-checker=false
PUT configurations
Content-Type: application/json
Request Body: { }
{
"changes": {
"globalConfiguration": {
"maker-checker": false
}
}
}
Cache
The following settings are possible for cache:
- No Caching: caching turned off
- Single node: caching on for single instance deployments of platorm (works for multiple tenants but only one tomcat)
By default caching is set to No Caching. Switching between caches results in the cache been clear e.g. from Single node to No cache and back again would clear down the single node cache.
Retrieve Cache Types
Returns the list of caches.
Example Requests:
caches
GET https://DomainName/api/v1/caches
[
{
"cacheType": {
"id": 1,
"code": "cacheType.noCache",
"value": "No cache"
},
"enabled": true
},
{
"cacheType": {
"id": 2,
"code": "cacheType.singleNode",
"value": "Single node"
},
"enabled": false
},
{
"cacheType": {
"id": 3,
"code": "cacheType.multiNode",
"value": "Multi node"
},
"enabled": false
}
]
Switch Cache
Switches the cache to chosen one.
PUT https://DomainName/api/v1/caches
PUT caches
Content-Type: application/json
Request Body:
{
"cacheType": 2
}
{
"changes": {
"cacheType": 2
}
}
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 modified 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://DomainName/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://DomainName/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://DomainName/api/v1/codes/{codeId}
{
"id": 1,
"name": "Customer Identifier",
"systemDefined": true
}
Update a Code
Updates the details of a code if it is not system defined.
PUT https://DomainName/api/v1/codes/{codeId}
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://DomainName/api/v1/codes/{codeId}
DELETE codes/4
Content-Type: application/json
{
"resourceId": 4
}
Code Values
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 modified 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 Value
POST https://DomainName/api/v1/codes/1/codevalues
POST codes/1/codevalues
Content-Type: application/json
Request Body:
{
"name":"Ration Card",
"position":"1"
}
{
"resourceId": 4
}
List Code Values
Returns the list of Code Values for a given Code
Example Requests:
codes/1/codevalues
GET https://DomainName/api/v1/codes/{codeId}/codevalues
[
{
"id": 1,
"name": "Passport",
"position": 0
},
{
"id": 2,
"name": "Id",
"position": 0
},
{
"id": 3,
"name": "Drivers License",
"position": 0
},
{
"id": 4,
"name": "Any Other Id Type",
"position": 0
},
{
"id": 5,
"name": "Ration Card",
"position": 1
}
]
Retrieve a Code Value
Returns the details of a Code Value
Example Requests:
codes/1/codevalues/1
GET https://DomainName/api/v1/codes/{codeId}/codevalues/{codevalueId}
{
"id": 1,
"name": "Passport",
"position": 0
}
Update a Code Value
Updates the details of a code value.
PUT https://DomainName/api/v1/codes/{codeId}/codevalues/{codevalueId}
PUT codes/1/codevalues/1
Content-Type: application/json
Request Body:
{
"name": "Indian Passport",
"position":2
}
{
"resourceId": 1,
"changes": {
"name": "Indian Passport",
"position": 2
}
}
Delete a Code Value
Deletes a code value
DELETE https://DomainName/api/v1/codes/{codeId}/codevalues/{codevalueId}
DELETE codes/1/codevalues/5
Content-Type: application/json
{
"resourceId": 5
}
Audits
Every non-read Mifos API request is audited. A fully processed request can
not be changed or deleted. See maker checker api for situations where an audit is not
fully processed.
Permissions: To search and look at audit entries a user needs to be attached to a role
that has one of the ALL_FUNCTIONS, ALL_FUNCTIONS_READ or READ_AUDIT permissions.
Data Scope: A user can only see audits that are within their data scope. However,
'head office' users can see all audits including those that aren't office/branch related
e.g. Loan Product changes.
List Audits
Get a list of audits that match the criteria supplied, and are within the requestors' data scope.
Arguments
- actionName
- optional
- Examples: CREATE, UPDATE, DISBURSE
- entityName
- optional
- Examples: CLIENT, LOAN, FUND
- resourceId
- optional, The id value of the entityName
- makerId
- optional, The id value of the application user creating the entry
- makerDateTimeFrom
- optional, Get entries created on or after this
- Example: 2013-04-10 08:00:00
- makerDateTimeTo
- optional, Get entries created on or before this
- Example: 2013-05-10 08:00:00
- checkerId
- optional, The id value of the application user that checked (approved) the entry
- checkerDateTimeFrom
- optional, Get entries checked on or after this
- Example: 2013-04-10 08:00:00
- checkerDateTimeTo
- optional, Get entries checked on or before this
- Example: 2013-05-10 18:00:00
- processingResult
- optional, The enum value of the processing status
- values:
0: Invalid
1: processed
2: awaiting.approval
3: rejected - officeId
- optional, The id value of the office/branch associated with the entry (if there is one)
- groupId
- optional, The id value of the group associated with the entry (if there is one). A group is a general idea and may be a Center, a Group, a Communal Bank or other.
- clientId
- optional, The id value of the client associated with the entry (if there is one)
- loanId
- optional, The id value of the loan associated with the entry (if there is one)
- savingsAccountId
- optional, The id value of the savings account associated with the entry (if there is one)
- includeJson
- optional, Values are true, false. Default is false.
Example Requests:
audits
audits?fields=madeOnDate,maker,processingResult
audits?makerDateTimeFrom=2013-03-25 08:00:00&makerDateTimeTo=2013-04-04 18:00:00
audits?officeId=1
audits?officeId=1&includeJson=true
GET https://DomainName/api/v1/audits
[
{
"id": 671,
"actionName": "PERMISSIONS",
"entityName": "ROLE",
"resourceId": 6,
"maker": "keithwoodlock",
"madeOnDate": 1365014262000,
"processingResult": "processed"
},
{
"id": 670,
"actionName": "CREATE",
"entityName": "CLIENTNOTE",
"resourceId": 287,
"maker": "keithwoodlock",
"madeOnDate": 1365014204000,
"processingResult": "awaiting.approval",
"officeName": "my office",
"clientName": "gg ggg"
},
{
"id": 668,
"actionName": "UPDATE",
"entityName": "PERMISSION",
"maker": "keithwoodlock",
"madeOnDate": 1365014186000,
"processingResult": "processed"
},
{
"id": 667,
"actionName": "CREATE",
"entityName": "CLIENTNOTE",
"resourceId": 286,
"maker": "keithwoodlock",
"madeOnDate": 1365014169000,
"processingResult": "processed",
"officeName": "my office name",
"clientName": "gg ggg"
},
{
"id": 666,
"actionName": "CREATE",
"entityName": "CLIENT",
"resourceId": 363,
"maker": "keithwoodlock",
"madeOnDate": 1365012843000,
"processingResult": "awaiting.approval",
"officeName": "my office name"
},
{
"id": 657,
"actionName": "CREATE",
"entityName": "CLIENT",
"resourceId": 362,
"maker": "ii",
"madeOnDate": 1364953928000,
"checker": "ii",
"checkedOnDate": 1365010060000,
"processingResult": "processed",
"officeName": "my office name",
"clientName": "gg ggg"
},
{
"id": 645,
"actionName": "CREATE",
"entityName": "LOAN",
"resourceId": 373,
"maker": "keithwoodlock",
"madeOnDate": 1364860260000,
"checker": "keithwoodlock",
"checkedOnDate": 1364861222000,
"processingResult": "processed",
"officeName": "another office",
"clientName": "another client",
"loanAccountNo": "000000373"
},...
]
Audit Search Template
This is a convenience resource. It can be useful when building an Audit Search UI. "appUsers" are data scoped to the office/branch the requestor is associated with.
Example Requests:
audits/searchtemplate
audits/searchtemplate?fields=actionNames
GET https://DomainName/api/v1/audits/searchtemplate
{
"appUsers": [
{
"id": 30,
"username": "user 1"
},
{
"id": 28,
"username": "user 2"
},
{
"id": 35,
"username": "user 3"
},...
],
"actionNames": [
"CREATE",
"DELETE",
"UPDATE",
"ACTIVATE",
"ADJUST",
"APPROVALUNDO",
"APPROVE",
"APPROVEINPAST",
"BULKREASSIGN",
"CALCULATEINTEREST",
"CLOSE",
"CLOSEASRESCHEDULED",
"CREATEHISTORIC",
"DEPOSIT",
"DEREGISTER",
"DISBURSALUNDO",
"DISBURSE",
"DISBURSEINPAST",
"INTEREST",
"PERMISSIONS",
"REGISTER",
"REJECT",...
],
"entityNames": [
"CALENDAR",
"CENTER",
"CHARGE",
"CLIENT",
"CLIENTIDENTIFIER",
"CLIENTIMAGE",
"CLIENTNOTE",
"CODE",
"CODEVALUE",
"COLLATERAL",
"CONFIGURATION",
"CURRENCY",
"DATATABLE",
"DEPOSITACCOUNT",
"DEPOSITNOTE",
"DEPOSITPRODUCT",
"DOCUMENT",
"FUND",
"GLACCOUNT",
"GLCLOSURE",
"GROUP",
"GROUPNOTE",...
],
"processingResults": [
{
"id": 0,
"processingResult": "invalid"
},
{
"id": 1,
"processingResult": "processed"
},
{
"id": 2,
"processingResult": "awaiting.approval"
},
{
"id": 3,
"processingResult": "rejected"
}
]
}
Retrieve an Audit Entry
Example Requests:
audits/20
audits/20?fields=madeOnDate,maker,processingResult
GET https://DomainName/api/v1/audits
{
"id": 20,
"actionName": "REPAYMENT",
"entityName": "LOAN",
"resourceId": 868,
"maker": "dataentry1",
"madeOnDate": 1358449025000,
"processingResult": "processed",
"commandAsJson": "{\"transactionDate\":\"28 September 2012\",\"transactionAmount\":\"1,967.00\",\"locale\":\"en\",\"dateFormat\":\"dd MMMM yyyy\"}",
"officeName": "another office",
"clientName": "another client",
"loanAccountNo": "23"
}
Maker Checker (or 4-eye) functionality
Mifos X Maker Checker functionality allows an MFI to define transactions as having a maker and a checker phase. One user enters, deletes or changes data. Then, another user that has "Checker" rights for that transaction, can inspect and approve the data.
By default, Maker Checker functionality is disabled. See Update Global Configuration to enable/disable Maker Checker functionality at a global level.
Additionally, Maker Checker functionality for each transaction (permission) is disabled by default. see Enable/Disable Permissions for Maker Checker to enable/disable Maker Checker functionality at a transaction (permission) level.
Finally, to give checking rights to a user (via a role associated with the user) see Update a Role's Permissions
For example,
{
"permissions":{
"CREATE_GUARANTOR_CHECKER":true,
"CREATE_CLIENT_CHECKER":true
}
}
will give checking rights for CREATE_GUARANTOR and CREATE_CLIENT
Alternatively, the special permissions ALL_FUNCTIONS or CHECKER_SUPER_USER will give blanket checking rights.
When a user "makes" an entry that is enabled for Maker Checker, it is audited and the audit status is set to a value of 2 (awaiting.approval).
Checkers can only Check and approve entries that they have been permitted to check.Checkers can only Check and approve entries that are within their data scope. However, 'head office' Checkers can Check and approve all entries including those that aren't office/branch related (as long as they have the Checker permissions) e.g. Loan Product changes.
List Maker Checker Entries
Get a list of entries that can be checked by the requestor that match the criteria supplied.
Arguments
- actionName
- optional
- Examples: CREATE, UPDATE, DISBURSE
- entityName
- optional
- Examples: CLIENT, LOAN, FUND
- resourceId
- optional, The id value of the entityName
- makerId
- optional, The id value of the application user creating the entry
- makerDateTimeFrom
- optional, Get entries created on or after this
- Example: 2013-04-10 08:00:00
- makerDateTimeTo
- optional, Get entries created on or before this
- Example: 2013-05-10 08:00:00
- officeId
- optional, The id value of the office/branch associated with the entry (if there is one)
- groupId
- optional, The id value of the group associated with the entry (if there is one). A group is a general idea and may be a Center, a Group, a Communal Bank or other.
- clientId
- optional, The id value of the client associated with the entry (if there is one)
- loanId
- optional, The id value of the loan associated with the entry (if there is one)
- savingsAccountId
- optional, The id value of the savings account associated with the entry (if there is one)
- includeJson
- optional, Values are true, false. Default is false.
Example Requests:
makercheckers
makercheckers?fields=madeOnDate,maker,processingResult
makercheckers?makerDateTimeFrom=2013-03-25 08:00:00&makerDateTimeTo=2013-04-04 18:00:00
makercheckers?officeId=1
makercheckers?officeId=1&includeJson=true
GET https://DomainName/api/v1/makercheckers
[
{
"id": 654,
"actionName": "CREATE",
"entityName": "LOANPRODUCT",
"resourceId": 15,
"maker": "keithwoodlock",
"madeOnDate": 1364924512000,
"processingResult": "awaiting.approval"
},
{
"id": 666,
"actionName": "CREATE",
"entityName": "CLIENT",
"resourceId": 363,
"maker": "keithwoodlock",
"madeOnDate": 1365012843000,
"processingResult": "awaiting.approval",
"officeName": "my office name"
},
{
"id": 670,
"actionName": "CREATE",
"entityName": "CLIENTNOTE",
"resourceId": 287,
"maker": "keithwoodlock",
"madeOnDate": 1365014204000,
"processingResult": "awaiting.approval",
"officeName": "my office name",
"clientName": "gg ggg"
}
]
Maker Checker Search Template
This is a convenience resource. It can be useful when building a Checker Inbox UI. "appUsers" are data scoped to the office/branch the requestor is associated with. "actionNames" and "entityNames" returned are those that the requestor has Checker approval permissions for.
Example Requests:
makercheckers/searchtemplate
makercheckers/searchtemplate?fields=entityNames
GET https://DomainName/api/v1/audits/searchtemplate
{
"appUsers": [
{
"id": 30,
"username": "user 1"
},
{
"id": 28,
"username": "user 2"
},
{
"id": 35,
"username": "user 3"
},...
],
"actionNames": [
"CREATE",
"DELETE",
"UPDATE",
"ACTIVATE",
"ADJUST",
"APPROVALUNDO",
"APPROVE",...
],
"entityNames": [
"CALENDAR",
"CENTER",
"CHARGE",
"CLIENT",
"CLIENTIDENTIFIER",...
]
}
Approve Maker Checker Entry
POST https://DomainName/api/v1/makercheckers/{auditId}?command=approve
POST makercheckers/1?command=approve
Content-Type: application/json
{ "auditId": 1 }
Delete Maker Checker Entry
DELETE https://DomainName/api/v1/makercheckers/{auditId}
DELETE makercheckers/1
Content-Type: application/json
{ "auditId": 1 }
MIFOSX-BATCH JOBS
Batch jobs (also known as cron jobs on Unix-based systems) are a series of back-end jobs executed on a computer at a particular time defined in job's cron expression.
At any point, you can view the list of batch jobs scheduled to run along with other details specific to each job. Manually you can execute the jobs at any point of time.
The scheduler status can be either "Active" or "Standby". If the scheduler status is Active, it indicates that all batch jobs are running/ will run as per the specified schedule.If the scheduler status is Standby, it will ensure all scheduled batch runs are suspended.
Retrieve Scheduler Jobs
Returns the list of jobs.
Example Requests:
jobs
GET https://DomainName/api/v1/jobs
[
{
"jobId": 1,
"displayName": "Update loan Summary",
"cronExpression": "0 0 22 1/1 * ? *",
"active": false,
"currentlyRunning": false,
"lastRunHistory": {
"version": 17,
"jobRunStartTime": "Jul 26, 2013 1:38:26 PM",
"jobRunEndTime": "Jul 26, 2013 1:38:26 PM",
"status": "success",
"triggerType": "application"
}
},
{
"jobId": 2,
"displayName": "Update Loan Arrears Ageing",
"nextRunTime": "Jul 27, 2013 12:01:00 AM",
"cronExpression": "0 1 0 1/1 * ? *",
"active": true,
"currentlyRunning": false,
"lastRunHistory": {
"version": 18,
"jobRunStartTime": "Jul 26, 2013 4:05:32 PM",
"jobRunEndTime": "Jul 26, 2013 4:05:32 PM",
"status": "success",
"triggerType": "application"
}
},
{
"jobId": 3,
"displayName": "Update Loan Paid In Advance",
"nextRunTime": "Jul 27, 2013 12:05:00 AM",
"cronExpression": "0 5 0 1/1 * ? *",
"active": true,
"currentlyRunning": false,
"lastRunHistory": {
"version": 16,
"jobRunStartTime": "Jul 26, 2013 4:15:47 PM",
"jobRunEndTime": "Jul 26, 2013 4:15:47 PM",
"status": "success",
"triggerType": "application"
}
},
{
"jobId": 4,
"displayName": "Apply Annual Fee For Savings",
"nextRunTime": "Jul 26, 2013 10:20:00 PM",
"cronExpression": "0 20 22 1/1 * ? *",
"active": true,
"currentlyRunning": false,
"lastRunHistory": {
"version": 11,
"jobRunStartTime": "Jul 26, 2013 12:00:37 PM",
"jobRunEndTime": "Jul 26, 2013 12:00:38 PM",
"status": "success
"triggerType": "application"
}
},
{
"jobId": 5,
"displayName": "Apply Holidays To Loans",
"nextRunTime": "Jul 27, 2013 12:00:00 PM",
"cronExpression": "0 0 12 * * ?",
"active": true,
"currentlyRunning": false,
"lastRunHistory": {
"version": 16,
"jobRunStartTime": "Jul 26, 2013 4:31:54 PM",
"jobRunEndTime": "Jul 26, 2013 4:31:55 PM",
"status": "success",
"triggerType": "application"
}
}
]
Retrieve a Job
Returns the details of a Job.
Example Requests:
jobs/5
GET https://DomainName/api/v1/jobs/{jobId}
https://localhost:8443/mifosng-provider/api/v1/jobs/5
{
"jobId": 5,
"displayName": "Apply Holidays To Loans",
"nextRunTime": "Jul 27, 2013 12:00:00 PM",
"cronExpression": "0 0 12 * * ?",
"active": true,
"currentlyRunning": false,
"lastRunHistory": {
"version": 16,
"jobRunStartTime": "Jul 26, 2013 4:31:54 PM",
"jobRunEndTime": "Jul 26, 2013 4:31:55 PM",
"status": "success",
"triggerType": "application"
}
}
Update a Job
Updates the details of a job.
PUT https://DomainName/api/v1/jobs/{jobId}
PUT jobs/1
Content-Type: application/json
{
"displayName":"Update loan Summary",
"cronExpression":"0 0 22 1/1 * ? *",
"active":"true"
}
Run a Job
Manually Execute Specific Job.
POST https://DomainName/api/v1/jobs/{jobId}?command=executeJob
POST jobs/1?command=executeJob
Retrieve Job Run History
Example Requests:
jobs/5/runhistory?offset=0&limit=200
GET https://DomainName/api/v1/jobs/{jobid}/runhistory?offset=0&limit=200
{
"totalFilteredRecords": 8,
"pageItems": [
{
"version": 1,
"jobRunStartTime": "Jul 16, 2013 12:00:00 PM",
"jobRunEndTime": "Jul 16, 2013 12:00:00 PM",
"status": "success",
"triggerType": "cron"
},
{
"version": 2,
"jobRunStartTime": "Jul 17, 2013 12:00:00 PM",
"jobRunEndTime": "Jul 17, 2013 12:00:00 PM",
"status": "success",
"triggerType": "cron"
},
{
"version": 3,
"jobRunStartTime": "Jul 18, 2013 12:00:00 PM",
"jobRunEndTime": "Jul 18, 2013 12:00:01 PM",
"status": "success",
"triggerType": "cron"
},
{
"version": 4,
"jobRunStartTime": "Jul 19, 2013 12:00:00 PM",
"jobRunEndTime": "Jul 19, 2013 12:00:00 PM",
"status": "success",
"triggerType": "cron"
},
{
"version": 5,
"jobRunStartTime": "Jul 20, 2013 11:16:07 AM",
"jobRunEndTime": "Jul 20, 2013 11:16:07 AM",
"status": "success",
"triggerType": "application"
},
{
"version": 6,
"jobRunStartTime": "Jul 20, 2013 11:35:05 AM",
"jobRunEndTime": "Jul 20, 2013 11:35:05 AM",
"status": "success",
"triggerType": "application"
},
{
"version": 7,
"jobRunStartTime": "Jul 20, 2013 12:00:00 PM",
"jobRunEndTime": "Jul 20, 2013 12:00:00 PM",
"status": "success",
"triggerType": "cron"
},
{
"version": 8,
"jobRunStartTime": "Jul 22, 2013 12:00:00 PM",
"jobRunEndTime": "Jul 22, 2013 12:00:00 PM",
"status": "success",
"triggerType": "cron"
}
]
}
Retrieve Scheduler Status
Returns the scheduler status.
Example Requests:
scheduler
GET https://DomainName/api/v1/scheduler
https://localhost:8443/mifosng-provider/api/v1/scheduler
{
"active": true
}
Activate Scheduler Jobs
Activates the scheduler job service.
POST https://DomainName/api/v1/scheduler?command=start
POST scheduler?command=start
Suspend Scheduler Jobs
Suspends the scheduler job service.
POST https://DomainName/api/v1/scheduler?command=stop
POST scheduler?command=stop
Funds
Create a Fund
Creates a fund.
POST https://DomainName/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://DomainName/api/v1/funds
[
{
"id": 1,
"name": "EU Agri Fund"
}
]
Retrieve a Fund
Returns the details of a Fund.
Example Requests:
funds/1
GET https://DomainName/api/v1/funds/{fundId}
{
"id": 1,
"name": "EU Agri Fund"
}
Update a Fund
Updates the details of a fund.
PUT https://DomainName/api/v1/funds/{fundId}
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 significance is whether this staff member is a loan officer or not.
Create a staff member
Creates a staff member.
POST https://DomainName/api/v1/staff
POST staff
Content-Type: application/json
Request Body:
{
"officeId": 1,
"firstname": "John",
"lastname": "Doe",
"isLoanOfficer": "true",
"externalId": "17H",
"mobileNo": "+353851239876"
}
{
"officeId": 1,
"resourceId": 1
}
Retrieve Staff
Returns the list of staff members.
Example Requests:
staff
GET https://DomainName/api/v1/staff
[
{
"id": 1,
"firstname": "John",
"lastname": "Doe",
"displayName": "Doe, John",
"officeId": 1,
"officeName": "Head Office",
"isLoanOfficer": true,
"externalId": "17H"
}
]
Retrieve a Staff Member
Returns the details of a Staff Member.
Example Requests:
staff/1
GET https://DomainName/api/v1/staff/{staffId}
{
"id": 1,
"firstname": "John",
"lastname": "Doe",
"displayName": "Doe, John",
"officeId": 1,
"officeName": "Head Office",
"isLoanOfficer": true,
"externalId": "17H"
}
Update a Staff Member
Updates the details of a staff member.
PUT https://DomainName/api/v1/staff/{staffId}
PUT staff/1
Content-Type: application/json
Request Body:
{
"isLoanOfficer": "false",
"externalId": "17Hbb"
}
{
"officeId": 1,
"resourceId": 1,
"changes": {
"isLoanOfficer": false,
"externalId": "17Hbb"
}
}
Charges
Its typical for MFIs to add extra costs for their financial products. These are typically Fees or Penalties.
A Charge on mifos platform is what we use to model both Fees and Penalties.
At present we support defining charges for use in both loan and saving products.
Field Descriptions |
| name |
| Name associated with this charge. |
| chargeAppliesTo |
| Enumeration for indicating whether charge is to be applicable for loans or savings. 1=Loans, 2=Savings Once a charge definiton has been created, this attribute cannot be changed at any point. |
| active |
| Boolean flag determines if the charge is currently active. |
| penalty |
| Boolean flag determines if the charge is a penalty. If false the charge is considered a Fee |
| currencyCode |
| A three letter ISO code of currency. |
| chargeCalculationType |
| Enumeration for indicating whether charge amount is flat or percentage based: 1=Flat, 2=% of Amount Used in combination with amount parameter e.g 1 % of Amount or 3.50 Flat For loans, % of Amount refers to the loan principal disbursed. For savings, % of Amount can be used with 'withrawal fees' and refers to the amount withdrawn. |
| amount |
| The charge amount. Used in combination with chargeCalculationType parameter. e.g 1 % of Amount or 3.50 Flat |
| minCap |
| Optional: Can be used when a '% of Amount' value is used for chargeCalculationType.
Used to enforce a minimum charge amount in cases where the calculated amount is less than the minimum amount provided. e.g. A 2% fee with a minimum cap of 500: In case of a 5000 loan, the 2% is 100, and therefore automatically 500 is used as the value of the charge. |
| maxCap |
| Optional: Can be used when a '% of Amount' value is used for chargeCalculationType.
Used to enforce a maximum charge amount in cases where the calculated amount is greater than the maximum amount provided. e.g. A 2% fee, with a maximum of 2000.: In case of a 150000 loan, the 2% adds up to 3000 charge, and therefore the maximum cap of 2000 will be used. |
| chargeTimeType |
| An enumeration indicating the time at which the charge becomes due:
1 = Disbursement : Applicable for loans and deducted at the time of loan disbursement. |
| chargePaymentMode |
| Applicable to loan charges only: Enumeration for indicating whether charge is to be paid through an Account Transfer from savings or through Regular payment mode. 0=Regular, 1=Account Transfer |
| feeOnMonthDay |
| Used along with monthDayFormat to indicate the recurring charge due date starting on a given day of the month and follow specified feeInterval. e.g. fee due date starting on 10 May with feeInterval of two (2) months then a recurring fee on 10th of every two months is applied to savings account. monthDayFormat indicates day and month formatting used e.g. "dd MMM" for 10 May This field is mandatory if chargeTimeType is of type Monthly Fee |
| feeInterval |
| Fee to be applied on a specified interval (number of months). This field is mandatory if chargeTimeType is of type Monthly Fee |
Retrieve Charge 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:
charges/template
GET https://DomainName/api/v1/charges/template
{
"active": false,
"penalty": false,
"currencyOptions": [
{
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
],
"chargeCalculationTypeOptions": [
{
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
{
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
}
],
"chargeAppliesToOptions": [
{
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
{
"id": 2,
"code": "chargeAppliesTo.savings",
"value": "Savings"
}
],
"chargeTimeTypeOptions": [
{
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
{
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
{
"id": 3,
"code": "chargeTimeType.savingsActivation",
"value": "Savings Activation"
},
{
"id": 5,
"code": "chargeTimeType.withdrawalFee",
"value": "Withdrawal Fee"
},
{
"id": 6,
"code": "chargeTimeType.annualFee",
"value": "Annual Fee"
},
{
"id": 7,
"code": "chargeTimeType.monthlyFee",
"value": "Monthly Fee"
}
],
"chargePaymetModeOptions": [
{
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
},
{
"id": 1,
"code": "chargepaymentmode.accounttransfer",
"value": "Account transfer"
}
],
"loanChargeCalculationTypeOptions": [
{
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
{
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
}
],
"loanChargeTimeTypeOptions": [
{
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
{
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
}
],
"savingsChargeCalculationTypeOptions": [
{
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
{
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
}
],
"savingsChargeTimeTypeOptions": [
{
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
{
"id": 3,
"code": "chargeTimeType.savingsActivation",
"value": "Savings Activation"
},
{
"id": 5,
"code": "chargeTimeType.withdrawalFee",
"value": "Withdrawal Fee"
},
{
"id": 6,
"code": "chargeTimeType.annualFee",
"value": "Annual Fee"
},
{
"id": 7,
"code": "chargeTimeType.monthlyFee",
"value": "Monthly Fee"
}
]
}
Create/Define a Charge
Define a new charge that can later be associated with loans and savings through their respective product definitions or directly on each account instance.
POST https://DomainName/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",
"chargePaymentMode": "1",
"active": true
}
{
"resourceId": 1
}
POST charges
Content-Type: application/json
Request Body:
{
"locale": "en",
"name": "Default Penalty",
"amount": "2",
"currencyCode": "USD",
"chargeAppliesTo": "1",
"chargeTimeType": "2",
"chargeCalculationType": "2",
"chargePaymentMode": "1",
"active": "true",
"penalty": "true",
"minCap": 50.00,
"maxCap": 100.00
}
{
"resourceId": 4
}
POST charges
Content-Type: application/json
Request Body:
{
"locale": "en",
"name": "Annuaul Fee",
"amount": "20",
"currencyCode": "USD",
"chargeAppliesTo": "2",
"chargeTimeType": "6",
"chargeCalculationType": "1",
"chargePaymentMode": "1",
"active": "true",
"penalty": "false"
}
{
"resourceId": 5
}
POST charges
Content-Type: application/json
Request Body:
{
"locale": "en",
"name": "Quarterly Fee",
"amount": "5",
"currencyCode": "USD",
"chargeAppliesTo": "2",
"chargeTimeType": "7",
"feeOnMonthDay": "10 May",
"monthDayFormat": "dd MMM",
"feeInterval": "4",
"chargeCalculationType": "1",
"active": "true",
"penalty": "false"
}
{
"resourceId": 6
}
Retrieve Charges
Returns the list of defined charges.
Example Requests:
charges
GET https://DomainName/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.56,
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode":{
"id":1,
"code":"chargepaymentmode.accounttransfer",
"value":"Account transfer"
}
},
{
"id": 54,
"chargeId": 12,
"name": "Loan service fee 2",
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeCalculationType": {
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
},
"percentage": 2.000000,
"amountPercentageAppliedTo": 14000.000000,
"currency": {
"code": "KES",
"name": "Kenyan Shilling",
"decimalPlaces": 2,
"displaySymbol": "KSh",
"nameCode": "currency.KES",
"displayLabel": "Kenyan Shilling (KSh)"
},
"amount": 500.000000,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 500.000000,
"amountOrPercentage": 2.000000,
"penalty": false,
"chargePaymentMode": {
"id": 1,
"code": "chargepaymentmode.accounttransfer",
"value": "Account transfer"
},
"paid": false,
"waived": false,
"chargePayable": true,
"minCap": 500.000000,
"maxCap": 1000.000000
},
]
Retrieve a Charge
Returns the details of a defined Charge.
Example Requests:
charges/1
GET https://DomainName/api/v1/charges/{chargeId}
{
"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.56,
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.disbursement",
"value": "Disbursement"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.loan",
"value": "Loan"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode":{
"id":1,
"code":"chargepaymentmode.accounttransfer",
"value":"Account transfer"
}
}
Update a Charge
Updates the details of a Charge.
PUT https://DomainName/api/v1/charges/{chargeId}
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://DomainName/api/v1/charges/{chargeId}
DELETE charges/1
Content-Type: application/json
{ "resourceId": 1 }
Accounting Rules
It is typical scenario in MFI's that non accountants pass journal entries on a regular basis. For Ex: A branch office might deposit their entire cash at hand to their Bank account at the end of a working day. The branch office users might not understand enough of accounting to figure out which account needs to get credited and which account needs to be debited to represent this transaction.
Enter accounting rules, an abstraction on top of manual Journal entires for enabling simpler data entry. An accounting rule can define any of the following abstractions
- A Simple journal entry where both the credit and debit account have been preselected
- A Simple journal entry where either credit or debit accounts have been limited to a pre-selected list of accounts (Ex: Debit account should be one of "Bank of America" of "JP Morgan" and credit account should be "Cash")
- A Compound journal entry where multiple debits and / or multiple credits may be made amongst a set of preselected list of accounts (Ex: Credit account should be either "Bank Of America" or "Cash" and debit account can be "Employee Salary" and/or "Miscellenous Expenses")
An accounting rule can also be optionally associated with a branch, so that only a particular Branch's users have access to the rule
Field Descriptions |
| name |
| Name of the accounting rule |
| description |
| A description of the accounting rule. |
| officeId |
| An Optional Office for this accounting rule is applicable. |
| accountToDebit |
| ID of the target account to be Debited |
| accountToCredit |
| ID of the target account to be Credited |
| debitTags |
| A list of accounting Tags. Any Ledger account with this tag can serve as the
account to be debited. This parameter is optional, if accountToDebit present in the request params |
| creditTags |
| A list of accounting Tags. Any Ledger account with this tag can serve as the
account to be credited. This parameter is optional, if accountToCredit present in the request params |
| allowMultipleDebitEntries |
| Allows passing multiple debit entries for the accounting rule |
| allowMultipleCreditEntries |
| Allows passing multiple credit entries for the accounting rule |
Retrieve Accounting Rule 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:
accountingrules/template
GET https://DomainName/api/v1/accountingrules/template
{
"systemDefined": false,
"allowedOffices": [{
"id": 1,
"name": "Head Office",
"nameDecorated": "Head Office"
}],
"allowedAccounts": [{
"id": 21,
"name": "Cash 2",
"parentId": 18,
"glCode": "20011",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"description": "Cash",
"nameDecorated": "............Cash 2",
"tagId": {
"id": 10,
"name": "asset tag"
}
},
{
"id": 9,
"name": "Employee Salary",
"parentId": 8,
"glCode": "456674",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 5,
"code": "accountType.expense",
"value": "EXPENSE"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "Employee Salary",
"tagId": {
"id": 14,
"name": "Expenses Tag"
}
}]
}
Create/Define a Accounting rule
Define a new Accounting rule.
Mandatory Fields |
| name, officeId, accountToDebit OR debitTags, accountToCredit OR creditTags. |
Optional Fields |
| description |
POST https://DomainName/api/v1/accountingrules
POST accountingrules
Content-Type: application/json
Request Body:
{
"name": "test",
"officeId": "1",
"accountToDebit": "21",
"accountToCredit": "9",
"description": "Employee salary"
}
{
"officeId":1,
"resourceId":1
}
POST accountingrules
Content-Type: application/json
Request Body:
{
"name": "fordocs",
"officeId": "1",
"debitTags": ["10","11"],
"allowMultipleDebitEntries": "true",
"creditTags": ["12","13"],
"allowMultipleCreditEntries": "true",
"description": "for api docs"
}
{
"officeId":1,
"resourceId":2
}
POST accountingrules
Content-Type: application/json
Request Body:
{
"name": "test123",
"officeId": "1",
"accountToDebit": "21",
"creditTags": ["12", "13"],
"allowMultipleCreditEntries": "false",
"description": "Employee salary"
}
{
"officeId":1,
"resourceId":3
}
POST accountingrules
Content-Type: application/json
Request Body:
{
"name": "fordocstest",
"officeId": "1",
"debitTags": ["10","11"],
"allowMultipleDebitEntries": "false",
"accountToCredit": "9",
"description": "for api docs"
}
{
"officeId":1,
"resourceId":4
}
Retrieve Accounting Rules
Returns the list of defined accounting rules.
Example Requests:
accountingrules
GET https://DomainName/api/v1/accountingrules
[{
"id": 1,
"officeId": 1,
"officeName": "Head Office",
"name": "test",
"description": "Employee salary",
"systemDefined": false,
"debitAccountHead": {
"id": 21,
"name": "Cash 2",
"glCode": "20011",
"disabled": false,
"manualEntriesAllowed": false
},
"creditAccountHead": {
"id": 9,
"name": "Employee Salary",
"glCode": "456674",
"disabled": false,
"manualEntriesAllowed": false
}
},
{
"id": 2,
"officeId": 1,
"officeName": "Head Office",
"name": "A L1",
"description": "aafff",
"systemDefined": false,
"debitAccountHead": {
"id": 3,
"name": "A L",
"glCode": "10003",
"disabled": false,
"manualEntriesAllowed": false
},
"creditAccountHead": {
"id": 4,
"name": "car loan",
"glCode": "10004",
"disabled": false,
"manualEntriesAllowed": false
}
}]
Retrieve a Accounting rule
Returns the details of a defined Accounting rule.
Example Requests:
accountingrules/1
GET https://DomainName/api/v1/accountingrules/{accountingruleId}
{
"id": 1,
"officeId": 1,
"officeName": "Head Office",
"name": "test",
"description": "Employee salary",
"systemDefined": false,
"debitAccountHead": {
"id": 21,
"name": "Cash 2",
"glCode": "20011",
"disabled": false,
"manualEntriesAllowed": false
},
"creditAccountHead": {
"id": 9,
"name": "Employee Salary",
"glCode": "456674",
"disabled": false,
"manualEntriesAllowed": false
}
}
Update a Accounting Rule
Updates the details of a Accounting rule.
PUT https://DomainName/api/v1/accountingrules/{accountingruleId}
PUT accountingrules/1
Content-Type: application/json
Request Body:
{
"name": "Employee Salary posting rule"
}
{
"resourceId": 1,
"changes": {
"name": "Employee Salary posting rule"
}
}
Delete a Accounting Rule
Deletes a Accounting rule.
DELETE https://DomainName/api/v1/accountingrules/{accountingruleId}
DELETE accountingrules/1
Content-Type: application/json
{ "resourceId": 1 }
Savings Product:
An MFIs savings product offerings are modeled using this API.
When creating savings accounts, the details from the savings product are used to auto fill details of the savings account application process.
Field Descriptions |
| name |
| The name of the product offering. |
| description |
| A description of the product offering. |
| currencyCode |
| Three letter ISO code representing currency. |
| digitsAfterDecimal |
| Override the currency default value for digitsAfterDecimal. |
| inMultiplesOf |
| Override the default value for rounding currency to multiples of provided value. |
| nominalAnnualInterestRate |
| The default interest rate set when creating savings accounts of this type of product. e.g. 5% Per year - It number here is always expressed as the Nominal APR. |
| interestCompoundingPeriodType |
| The period at which interest rate is compounded. 1=Daily, 4=Monthly (at end of month) |
| interestPostingPeriodType |
| The period at which interest rate is posted or credited to savings account. 4=Monthly (at end of month), 5=Quarterly (at end of quarter, 31st Mar, 30th Jun, 30th Sep, 31st Dec) |
| interestCalculationType |
| The interest calculation method used: 1=Daily Balance or 2=Average Daily Balance |
| interestCalculationDaysInYearType |
| The setting for number of days in year to use: 360=360 Days, 365=365 Days |
| minRequiredOpeningBalance |
| Optional: If provided, sets the minimum deposit amount required to open a savings account e.g. 2,000 |
| lockinPeriodFrequency |
| Optional: If provided, used along with lockinPeriodFrequencyType to indicate the length of time that the savings account is 'locked in' and withdrawals are not allowed. e.g. 6 Months |
| lockinPeriodFrequencyType |
| Optional: If provided, used along with lockinPeriodFrequency to indicate the length of time that the savings account is 'locked in' and withdrawals are not allowed. 0=Days, 1=Weeks, 2=Months, 3=Years e.g. 6 Months |
| withdrawalFeeForTransfers |
| Optional: Used along with withdrawalFeeAmount to indicate whether the withdrawal fee should be applied on the account for account transfers . |
| accountingRule |
| Specifies if accounting is enabled for the particular product and the type of the accounting rule to be used Example Values:1=NONE,2=CASH_BASED |
Retrieve Savings Product 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:
savingsproducts/template
GET https://Domain Name/api/v1/savingsproducts/template
{
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"interestCompoundingPeriodType": {
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
"interestPostingPeriodType": {
"id": 4,
"code": "savings.interest.posting.period.savingsInterestPostingPeriodType.monthly",
"value": "Monthly"
},
"interestCalculationType": {
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
"interestCalculationDaysInYearType": {
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
},
"accountingRule": {
"id": 1,
"code": "accountingRuleType.none",
"value": "NONE"
},
"currencyOptions": [
{
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
],
"interestCompoundingPeriodTypeOptions": [
{
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
{
"id": 2,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.weekly",
"value": "Weekly"
},
{
"id": 3,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.biweekly",
"value": "Bi-Weekly"
},
{
"id": 4,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.monthly",
"value": "Monthly"
},
{
"id": 5,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.quarterly",
"value": "Quarterly"
},
{
"id": 6,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.biannual",
"value": "Semi-Annual"
},
{
"id": 7,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.annual",
"value": "Annually"
},
{
"id": 8,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.nocompounding",
"value": "No Compounding - Simple Interest"
}
],
"interestPostingPeriodTypeOptions": [
{
"id": 4,
"code": "savings.interest.posting.period.savingsInterestPostingPeriodType.monthly",
"value": "Monthly"
},
{
"id": 5,
"code": "savings.interest.posting.period.savingsInterestPostingPeriodType.quarterly",
"value": "Quarterly"
},
{
"id": 6,
"code": "savings.interest.posting.period.savingsInterestPostingPeriodType.biannual",
"value": "Semi-Annual"
},
{
"id": 7,
"code": "savings.interest.posting.period.savingsInterestPostingPeriodType.annual",
"value": "Annually"
}
],
"interestCalculationTypeOptions": [
{
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
{
"id": 2,
"code": "savingsInterestCalculationType.averagedailybalance",
"value": "Average Daily Balance"
}
],
"interestCalculationDaysInYearTypeOptions": [
{
"id": 360,
"code": "savingsInterestCalculationDaysInYearType.days360",
"value": "360 Days"
},
{
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
}
],
"lockinPeriodFrequencyTypeOptions": [
{
"id": 0,
"code": "savings.lockin.savingsPeriodFrequencyType.days",
"value": "Days"
},
{
"id": 1,
"code": "savings.lockin.savingsPeriodFrequencyType.weeks",
"value": "Weeks"
},
{
"id": 2,
"code": "savings.lockin.savingsPeriodFrequencyType.months",
"value": "Months"
},
{
"id": 3,
"code": "savings.lockin.savingsPeriodFrequencyType.years",
"value": "Years"
}
],
"withdrawalFeeTypeOptions": [
{
"id": 1,
"code": "savingsWithdrawalFeesType.flat",
"value": "Flat"
},
{
"id": 2,
"code": "savingsWithdrawalFeesType.percent.of.amount",
"value": "% of Amount"
}
],
"paymentTypeOptions": [
{
"id": 14,
"name": "Wire Transfer",
"position": 0
},
{
"id": 13,
"name": "Cash",
"position": 1
}
],
"accountingRuleOptions": [
{
"id": 1,
"code": "accountingRuleType.none",
"value": "NONE"
},
{
"id": 2,
"code": "accountingRuleType.cash",
"value": "CASH BASED"
},
{
"id": 3,
"code": "accountingRuleType.accrual",
"value": "ACCRUAL BASED"
}
],
"accountingMappingOptions": {
"liabilityAccountOptions": [
{
"id": 15,
"name": "Savings Control",
"glCode": "50001",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 2,
"code": "accountType.liability",
"value": "LIABILITY"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "Savings Control",
"tagId": {
"id": 0
}
}
],
"assetAccountOptions": [
{
"id": 2,
"name": "Cash",
"glCode": "100001",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 16,
"name": "Savings Reference",
"glCode": "100007",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "Savings Reference",
"tagId": {
"id": 0
}
},
{
"id": 12,
"name": "HDFC Rajajinagar",
"glCode": "100015",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 1,
"name": "Loan Portfolio",
"glCode": "10003",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 7,
"name": "Interest Receivable",
"glCode": "10005",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 8,
"name": "Penalties Receivable",
"glCode": "10008",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 9,
"name": "Fee Receivable",
"glCode": "10009",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
}
],
"expenseAccountOptions": [
{
"id": 6,
"name": "Write Off Expenses",
"glCode": "60001",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 5,
"code": "accountType.expense",
"value": "EXPENSE"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 13,
"name": "Employee Salary",
"glCode": "60002",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 5,
"code": "accountType.expense",
"value": "EXPENSE"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 18,
"name": "Interest On Savings",
"glCode": "60003",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 5,
"code": "accountType.expense",
"value": "EXPENSE"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"nameDecorated": "Interest On Savings",
"tagId": {
"id": 0
}
}
],
"incomeAccountOptions": [
{
"id": 3,
"name": "Income from Interest",
"glCode": "40001",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 4,
"name": "Income from Fees",
"glCode": "40002",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
},
{
"id": 5,
"name": "Income from Penalties",
"glCode": "40004",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"tagId": {}
}
]
},
"chargeOptions" : [ { "active" : true,
"amount" : 200,
"chargeAppliesTo" : { "code" : "chargeAppliesTo.savings",
"id" : 2,
"value" : "Savings"
},
"chargeCalculationType" : { "code" : "chargeCalculationType.flat",
"id" : 1,
"value" : "Flat"
},
"chargePaymentMode" : { "code" : "chargepaymentmode.regular",
"id" : 0,
"value" : "chargepaymentmode.regular"
},
"chargeTimeType" : { "code" : "chargeTimeType.specifiedDueDate",
"id" : 2,
"value" : "Specified due date"
},
"currency" : { "code" : "USD",
"decimalPlaces" : 2,
"displayLabel" : "US Dollar ($)",
"displaySymbol" : "$",
"name" : "US Dollar",
"nameCode" : "currency.USD"
},
"id" : 4,
"name" : "Savings charge 1",
"penalty" : false
},
{ "active" : true,
"amount" : 300,
"chargeAppliesTo" : { "code" : "chargeAppliesTo.savings",
"id" : 2,
"value" : "Savings"
},
"chargeCalculationType" : { "code" : "chargeCalculationType.flat",
"id" : 1,
"value" : "Flat"
},
"chargePaymentMode" : { "code" : "chargepaymentmode.regular",
"id" : 0,
"value" : "chargepaymentmode.regular"
},
"chargeTimeType" : { "code" : "chargeTimeType.specifiedDueDate",
"id" : 2,
"value" : "Specified due date"
},
"currency" : { "code" : "USD",
"decimalPlaces" : 2,
"displayLabel" : "US Dollar ($)",
"displaySymbol" : "$",
"name" : "US Dollar",
"nameCode" : "currency.USD"
},
"id" : 5,
"name" : "Savings charge 2",
"penalty" : false
}
]
}
Create a Savings Product
Mandatory Fields |
| name, description, currencyCode, digitsAfterDecimal,inMultiplesOf, nominalAnnualInterestRate, interestCompoundingPeriodType, interestCalculationType, interestCalculationDaysInYearType,accountingRule |
Mandatory Fields for Cash based accounting (accountingRule = 2) |
| savingsReferenceAccountId, savingsControlAccountId, interestOnSavingsAccountId, incomeFromFeeAccountId, transfersInSuspenseAccountId, incomeFromPenaltyAccountId |
Optional Fields |
| minRequiredOpeningBalance, lockinPeriodFrequency, lockinPeriodFrequencyType, withdrawalFeeForTransfers, paymentChannelToFundSourceMappings, feeToIncomeAccountMappings, penaltyToIncomeAccountMappings, charges |
POST https://Domain Name/api/v1/savingsproducts
POST savingsproducts
Content-Type: application/json
Request Body:
{
"name": "Passbook Savings",
"description": "Daily compounding using Daily Balance, 5% per year, 365 days in year",
"currencyCode": "USD",
"digitsAfterDecimal": 2,
"inMultiplesOf": 0,
"locale": "en",
"nominalAnnualInterestRate": "5.0",
"interestCompoundingPeriodType": 1,
"interestPostingPeriodType":4,
"interestCalculationType": 1,
"interestCalculationDaysInYearType": "365",
"accountingRule":"1",
"charges":[{"id":"1"}]
}
{
"resourceId": 1
}
POST savingsproducts
Content-Type: application/json
Request Body:
{
"locale": "en",
"name": "New Passbook Savings ",
"description": "A savings product",
"currencyCode": "USD",
"digitsAfterDecimal": "2",
"inMultiplesOf": 0,
"nominalAnnualInterestRate": "15",
"interestCompoundingPeriodType": "1",
"interestPostingPeriodType": "4",
"interestCalculationType": "1",
"interestCalculationDaysInYearType": "365",
"minRequiredOpeningBalance": "50",
"lockinPeriodFrequency": "4",
"lockinPeriodFrequencyType": "1",
"withdrawalFeeForTransfers":false,
"accountingRule": "2",
"charges":[{"id":"1"},{"id":3}]
"savingsReferenceAccountId": "16",
"transfersInSuspenseAccountId": "16",
"savingsControlAccountId": "15",
"interestOnSavingsAccountId": "18",
"incomeFromFeeAccountId": "4",
"incomeFromPenaltyAccountId": "4",
"feeToIncomeAccountMappings":[
{
"chargeId":"6",
"incomeAccountId":"16"
}
],
"penaltyToIncomeAccountMappings":[
{
"chargeId":"4",
"incomeAccountId":"15"
}
],
"paymentChannelToFundSourceMappings": [
{
"paymentTypeId": "14",
"fundSourceAccountId": "2"
}
]
}
{
"resourceId": 1
}
Retrieve a Savings Product
Example Requests:
savingsproducts/1
savingsproducts/1?template=true
savingsproducts/1?fields=name,description
GET https://Domain Name/api/v1/savingsproducts/1
{
"id": 1,
"name": "savings product",
"description": "gtasga",
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"nominalAnnualInterestRate": 5.000000,
"interestCompoundingPeriodType": {
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
"interestPostingPeriodType": {
"id": 4,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.monthly",
"value": "Monthly"
},
"interestCalculationType": {
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
"interestCalculationDaysInYearType": {
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
},
"withdrawalFeeForTransfers": false,
"accountingRule": {
"id": 2,
"code": "accountingRuleType.cash",
"value": "CASH BASED"
},
"accountingMappings": {
"savingsReferenceAccount": {
"id": 12,
"name": "savings ref",
"glCode": "20"
},
"incomeFromFeeAccount": {
"id": 16,
"name": "income from savings fee",
"glCode": "24"
},
"incomeFromPenaltyAccount": {
"id": 17,
"name": "income from sav penalites",
"glCode": "25"
},
"interestOnSavingsAccount": {
"id": 15,
"name": "interest on savings",
"glCode": "23"
},
"savingsControlAccount": {
"id": 13,
"name": "savings ref tool kit",
"glCode": "21"
},
"transfersInSuspenseAccount": {
"id": 14,
"name": "saving transfers",
"glCode": "22"
}
},
"paymentChannelToFundSourceMappings": [
{
"paymentType": {
"id": 10,
"name": "check"
},
"fundSourceAccount": {
"id": 12,
"name": "savings ref",
"glCode": "20"
}
}
],
"feeToIncomeAccountMappings": [
{
"charge": {
"id": 11,
"name": "sav charge",
"active": false,
"penalty": false
},
"incomeAccount": {
"id": 16,
"name": "income from savings fee",
"glCode": "24"
}
}
],
"penaltyToIncomeAccountMappings": [
{
"charge": {
"id": 12,
"name": "sav 2",
"active": false,
"penalty": true
},
"incomeAccount": {
"id": 17,
"name": "income from sav penalites",
"glCode": "25"
}
}
],
"charges": []
}
Update a Savings Product
PUT https://Domain Name/api/v1/savingsproducts/{productId}
POST savingsproducts/1
Content-Type: application/json
Request Body:
{
"description": "Passbook Savings Lite.",
"locale": "en",
"interestRate": "5.73"
}
{
"resourceId": 1,
"changes": {
"description": "Passbook Savings Lite.",
"interestRate": 5.73,
"locale": "en"
}
}
Delete a Savings Product
DELETE https://Domain Name/api/v1/savingsproducts/{productId}
DELETE savingsproducts/1
Content-Type: application/json
{
"resourceId": 1
}
List Savings Products
Example Requests:
savingsproducts
savingsproducts?fields=name
GET https://Domain Name/api/v1/savingsproducts
[
{
"id": 1,
"name": "Savings product",
"description": "gtasga",
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"nominalAnnualInterestRate": 5.000000,
"interestCompoundingPeriodType": {
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
"interestPostingPeriodType": {
"id": 4,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.monthly",
"value": "Monthly"
},
"interestCalculationType": {
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
"interestCalculationDaysInYearType": {
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
},
"withdrawalFeeForTransfers": false,
"accountingRule": {
"id": 2,
"code": "accountingRuleType.cash",
"value": "CASH BASED"
}
}
]
Savings Account:
Savings accounts are instances of a praticular savings product created for an individual or group. An application process around the creation of accounts is also supported.
| Starting State | Action | Resultant State |
| - | Submit | Submitted and pending approval |
| Submitted and pending approval | Reject | Closed - Rejected |
| Submitted and pending approval | Withdrawn by Applicant | Closed - Withdrawn by Applicant |
| Submitted and pending approval | Approve | Approved |
| Approved | Undo Approval | Submitted and pending approval |
| Approved | Activate | Active |
Field Descriptions |
| clientId |
| The client you are creating the savings account for. Either clientId or groupId must be provided. |
| groupId |
| The group you are creating the savings account for. Either clientId or groupId must be provided. |
| productId |
| The id of the product used for this savings account. The savings account inherits the selected currency of the product and possibly other details if not overridden in the savings account creation request. |
| accountNo |
| The account no. associated with this loan. Is auto generated if not provided at creation time. |
| externalId |
| A place to put an external reference for this savings account useful in migrations e.g. The ID another system uses. If provided, it must be unique. |
| submittedOnDate |
| submittedOnDate must be provided when initially creating savings account application. locale and dateFormat parameters must be provided with this. |
| nominalAnnualInterestRate |
| The interest rate set for savings account e.g. 5% Per year - It is always expressed as the Nominal APR. |
| interestCompoundingPeriodType |
| The period at which interest rate is compounded. 1=Daily, 4=Monthly (at end of month) |
| interestPostingPeriodType |
| The period at which interest rate is posted or credited to savings account. The actual crediting or posting transaction is date as occurring on the day after the end of the period. 4=Monthly (at end of month), 5=Quarterly (at end of quarter, 31st Mar, 30th Jun, 30th Sep, 31st Dec), 7=Annually (at end of calendar year 31st Dec) |
| interestCalculationType |
| The interest calculation method used: 1=Daily Balance or 2=Average Daily Balance |
| interestCalculationDaysInYearType |
| The setting for number of days in year to use: 360=360 Days, 365=365 Days |
| minRequiredOpeningBalance |
| Optional: If provided, sets the minimum deposit amount required to open a savings account e.g. 2,000 |
| lockinPeriodFrequency |
| Optional: If provided, used along with lockinPeriodFrequencyType to indicate the length of time that the savings account is 'locked in' and withdrawals are not allowed. e.g. 6 Months |
| lockinPeriodFrequencyType |
| Optional: If provided, used along with lockinPeriodFrequency to indicate the length of time that the savings account is 'locked in' and withdrawals are not allowed. 0=Days, 1=Weeks, 2=Months, 3=Years e.g. 6 Months |
| withdrawalFeeForTransfers |
| Optional: Used along with withdrawalFeeAmount to indicate whether the withdrawal fee should be applied on the account for account transfers . |
Retrieve Savings Account 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:
savingsaccounts/template?clientId=1
savingsaccounts/template?clientId=1&productId=1
GET https://Domain Name/api/v1/savingsaccounts/template?clientId={clientId}
{
"clientId": 1,
"clientName": "small business",
"productOptions": [
{
"id": 1,
"name": "Passbook Savings"
}
]
}
GET https://Domain Name/api/v1/savingsaccounts/template?clientId={clientId}&productId={productId}
{
"clientId": 1,
"clientName": "small business",
"savingsProductId": 1,
"savingsProductName": "Passbook Savings",
"timeline": {},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"nominalAnnualInterestRate": 5,
"interestCompoundingPeriodType": {
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
"interestPostingPeriodType": {
"id": 4,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.monthly",
"value": "Monthly"
},
"interestCalculationType": {
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
"interestCalculationDaysInYearType": {
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
},
"productOptions": [
{
"id": 1,
"name": "Passbook Savings"
}
],
"fieldOfficerOptions": [
{
"id": 3,
"firstname": "Mrs.",
"lastname": "loanofficerB1",
"displayName": "loanofficerB1, Mrs.",
"officeId": 2,
"officeName": "branch 1",
"isLoanOfficer": true
},
{
"id": 1,
"firstname": "Mr.",
"lastname": "loanofficerHO",
"displayName": "loanofficerHO, Mr.",
"officeId": 1,
"officeName": "branch 1",
"isLoanOfficer": true
}
],
"interestCompoundingPeriodTypeOptions": [
{
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
{
"id": 4,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.monthly",
"value": "Monthly"
}
],
"interestPostingPeriodTypeOptions": [
{
"id": 4,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.monthly",
"value": "Monthly"
},
{
"id": 5,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.quarterly",
"value": "Quarterly"
},
{
"id": 7,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.annual",
"value": "Annually"
}
],
"interestCalculationTypeOptions": [
{
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
{
"id": 2,
"code": "savingsInterestCalculationType.averagedailybalance",
"value": "Average Daily Balance"
}
],
"interestCalculationDaysInYearTypeOptions": [
{
"id": 360,
"code": "savingsInterestCalculationDaysInYearType.days360",
"value": "360 Days"
},
{
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
}
],
"lockinPeriodFrequencyTypeOptions": [
{
"id": 0,
"code": "savings.lockin.savingsPeriodFrequencyType.days",
"value": "Days"
},
{
"id": 1,
"code": "savings.lockin.savingsPeriodFrequencyType.weeks",
"value": "Weeks"
},
{
"id": 2,
"code": "savings.lockin.savingsPeriodFrequencyType.months",
"value": "Months"
},
{
"id": 3,
"code": "savings.lockin.savingsPeriodFrequencyType.years",
"value": "Years"
}
],
"withdrawalFeeTypeOptions": [
{
"id": 1,
"code": "savingsWithdrawalFeesType.flat",
"value": "Flat"
},
{
"id": 2,
"code": "savingsWithdrawalFeesType.percent.of.amount",
"value": "% of Amount"
}
],
"chargeOptions": [
{
"id": 4,
"name": "Savings charge 1",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 200,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 2,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "chargepaymentmode.regular"
}
},
{
"id": 5,
"name": "Savings charge 2",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 300,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 2,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "chargepaymentmode.regular"
}
},
{
"id": 6,
"name": "Annual fee",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 50,
"chargeTimeType": {
"id": 6,
"code": "chargeTimeType.annualFee",
"value": "Annual Fee"
},
"chargeAppliesTo": {
"id": 2,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
},
{
"id": 7,
"name": "Quarterly fee",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 5,
"chargeTimeType": {
"id": 7,
"code": "chargeTimeType.monthlyFee",
"value": "Monthly Fee"
},
"chargeAppliesTo": {
"id": 2,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
},
"feeOnMonthDay": [
10,
5
],
"feeInterval": 4
}
]
}
Submit new savings application
Mandatory Fields |
| clientId or groupId, productId, submittedOnDate |
Optional Fields |
| accountNo, externalId, fieldOfficerId |
Inherited from Product (if not provided) |
| nominalAnnualInterestRate, interestCompoundingPeriodType, interestCalculationType, interestCalculationDaysInYearType, minRequiredOpeningBalance, lockinPeriodFrequency, lockinPeriodFrequencyType, withdrawalFeeForTransfers |
Minimal request: accountNo auto generated, remaining details inherited from savings product.
POST https://Domain Name/api/v1/savingsaccounts
POST savingsaccount
Content-Type: application/json
Request Body:
{
"clientId": 1,
"productId": 1,
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"submittedOnDate": "01 March 2011"
}
Minimal request: accountNo provided (must be unique), remaining details inherited from savings product.
POST savingsaccount
Content-Type: application/json
Request Body:
{
"clientId": 1,
"productId": 1,
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"submittedOnDate": "01 March 2011",
"accountNo": "SA000023",
"externalId": "SYS-23"
}
Full request: accountNo provided (must be unique), remaining details override details from savings product (except currency).
POST savingsaccount
Content-Type: application/json
Request Body:
{
"clientId": 1,
"productId": 1,
"fieldOfficerId": 1,
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"submittedOnDate": "01 March 2013",
"accountNo": "SA000023",
"externalId": "SYS-23",
"nominalAnnualInterestRate": "5.65",
"interestCompoundingPeriodType": 1,
"interestPostingPeriodType": 4,
"interestCalculationType": 1,
"interestCalculationDaysInYearType": 365,
"minRequiredOpeningBalance": "1,000",
"lockinPeriodFrequency": 6,
"lockinPeriodFrequencyType": 2,
"charges":[{"id":"1"}]
}
{
"officeId": 2,
"clientId": 1,
"savingsId": 1,
"resourceId": 1
}
Approve savings application
Approves savings application so long as its in 'Submitted and pending approval' state.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=approve
POST savingsaccount/1?command=approve
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"approvedOnDate": "01 March 2013"
}
{
"officeId": 2,
"clientId": 1,
"savingsId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 200,
"code": "savingsAccountStatusType.approved",
"value": "Approved",
"submittedAndPendingApproval": false,
"approved": true,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"approvedOnDate": "02 March 2013"
}
}
Undo approval savings application
Will move 'approved' savings application back to 'Submitted and pending approval' state.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=undoApproval
POST savingsaccount/1?command=undoApproval
Content-Type: application/json
Request Body:
{
}
{
"officeId": 2,
"clientId": 1,
"savingsId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 100,
"code": "savingsAccountStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"submittedAndPendingApproval": true,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"approvedOnDate": ""
}
}
Reject savings application
Rejects savings application so long as its in 'Submitted and pending approval' state.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=reject
POST savingsaccount/1?command=reject
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"rejectedOnDate": "03 March 2013"
}
{
"officeId": 2,
"clientId": 1,
"savingsId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 500,
"code": "savingsAccountStatusType.rejected",
"value": "Rejected",
"submittedAndPendingApproval": false,
"approved": false,
"rejected": true,
"withdrawnByApplicant": false,
"active": false,
"closed": true
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"rejectedOnDate": "03 March 2013",
"closedOnDate": "03 March 2013"
}
}
Withdraw savings application
Used when an applicant withdraws from the savings application. It must be in 'Submitted and pending approval' state.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=withdrawnByApplicant
POST savingsaccount/1?command=withdrawnByApplicant
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"withdrawnOnDate": "03 March 2013"
}
{
"officeId": 2,
"clientId": 1,
"savingsId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 400,
"code": "savingsAccountStatusType.withdrawn.by.applicant",
"value": "Withdrawn by applicant",
"submittedAndPendingApproval": false,
"approved": false,
"rejected": false,
"withdrawnByApplicant": true,
"active": false,
"closed": true
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"withdrawnOnDate": "03 March 2013",
"closedOnDate": "03 March 2013"
}
}
Activate a savings account
Results in an approved savings application being converted into an 'active' savings account.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=activate
POST savingsaccount/1?command=activate
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"activatedOnDate": "01 March 2013"
}
{
"officeId": 2,
"clientId": 1,
"savingsId": 1,
"resourceId": 1,
"changes": {
"status": {
"id": 300,
"code": "savingsAccountStatusType.active",
"value": "Active",
"submittedAndPendingApproval": false,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": true,
"closed": false
},
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"activatedOnDate": "01 March 2013"
}
}
Close a savings account
Results in an Activated savings application being converted into an 'closed' savings account.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=close
POST savingsaccount/5?command=close
Content-Type: application/json
Request Body:
{
"dateFormat":"dd MMMM yyyy",
"locale":"en",
"closedOnDate":"26 August 2013",
"note":"close note"
}
{
"officeId":1,
"clientId":1,
"savingsId":5,
"resourceId":5,
"changes":{
"status":{
"id":600,
"code":"savingsAccountStatusType.closed",
"value":"Closed",
"submittedAndPendingApproval":false,
"approved":false,
"rejected":false,
"withdrawnByApplicant":false,
"active":false,
"closed":true
},
"locale":"en",
"dateFormat":"dd MMMM yyyy",
"closedOnDate":"26 August 2013",
"note":"close note"
}
}
Calculate Interest on Savings Account
Calculates interest earned on a savings account based on todays date. It does not attempt to post or credit the interest on the account. That is responsibility of the Post Interest API that will likely be called by overnight process.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=calculateInterest
POST savingsaccount/1?command=calculateInterest
Content-Type: application/json
Request Body:
{
}
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 1
}
Post Interest on Savings Account
Calculates and Posts interest earned on a savings account based on todays date and whether an interest posting or crediting event is due.
POST https://Domain Name/api/v1/savingsaccounts/{savingsId}?command=postInterest
POST savingsaccount/1?command=postInterest
Content-Type: application/json
Request Body:
{
}
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 1
}
List savings applications/accounts
Example Requests:
savingsaccounts
savingsaccounts?fields=name
GET https://Domain Name/api/v1/savingsaccounts
{
"totalFilteredRecords": 1,
"pageItems": [
{
"id": 1,
"accountNo": "000000001",
"clientId": 1,
"clientName": "small business",
"savingsProductId": 1,
"savingsProductName": "Passbook Savings",
"fieldOfficerId": 0,
"status": {
"id": 100,
"code": "savingsAccountStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"submittedAndPendingApproval": true,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"timeline": {
"submittedOnDate": [
2013,
3,
1
]
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"nominalAnnualInterestRate": 5,
"interestCompoundingPeriodType": {
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
"interestPostingPeriodType": {
"id": 4,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.monthly",
"value": "Monthly"
},
"interestCalculationType": {
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
"interestCalculationDaysInYearType": {
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
},
"summary": {
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"accountBalance": 0
}
}
]
}
Retrieve a savings application/account:
Arguments
- associations
- optional, Either 'all' or a comma separated list of savings 'associations' (itemized below).
Associations are just extra pieces of data that you might or might not want to retrieve.- 'all': Gets data related to all associations e.g. ?associations=all.
- 'transactions': Gets data related to transactions on the account e.g. ?associations=transactions
- 'charges':Savings Account charges data.
Example Requests :
savingsaccounts/1
savingsaccounts/1?associations=all
GET https://DomainName/api/v1/savingsaccounts/{accountId}
{
"id": 1,
"accountNo": "000000001",
"clientId": 1,
"clientName": "small business",
"savingsProductId": 1,
"savingsProductName": "Passbook Savings",
"fieldOfficerId": 0,
"status": {
"id": 100,
"code": "savingsAccountStatusType.submitted.and.pending.approval",
"value": "Submitted and pending approval",
"submittedAndPendingApproval": true,
"approved": false,
"rejected": false,
"withdrawnByApplicant": false,
"active": false,
"closed": false
},
"timeline": {
"submittedOnDate": [
2013,
3,
1
]
},
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"nominalAnnualInterestRate": 5,
"interestCompoundingPeriodType": {
"id": 1,
"code": "savings.interest.period.savingsCompoundingInterestPeriodType.daily",
"value": "Daily"
},
"interestPostingPeriodType": {
"id": 4,
"code": "savings.interest.posting.period.savingsPostingInterestPeriodType.monthly",
"value": "Monthly"
},
"interestCalculationType": {
"id": 1,
"code": "savingsInterestCalculationType.dailybalance",
"value": "Daily Balance"
},
"interestCalculationDaysInYearType": {
"id": 365,
"code": "savingsInterestCalculationDaysInYearType.days365",
"value": "365 Days"
},
"summary": {
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"accountBalance": 0
}
}
Modify a savings application
Savings application can only be modified when in 'Submitted and pending approval' state. Once the application is approved, the details cannot be changed using this method. Specific api endpoints will be created to allow change of interest detail such as rate, compounding period, posting period etc
PUT https://Domain Name/api/v1/savingsaccounts/{accountsId}
PUT savingsaccounts/1
Content-Type: application/json
No Request Body:
{
"locale": "en",
"nominalAnnualInterestRate": "5.9999999999",
}
{
"officeId": 2,
"clientId": 1,
"savingsId": 1,
"resourceId": 1,
"changes": {
"nominalAnnualInterestRate": 5.9999999999,
"locale": "en"
}
}
Delete a savings application
At present we support hard delete of savings application so long as its in 'Submitted and pending approval' state. One the application is moves past this state, it is not possible to do a 'hard' delete of the application or the account. An API endpoint will be added to close/de-activate the savings account.
DELETE https://Domain Name/api/v1/savingsaccounts/{accountsId}
DELETE savingsaccounts/1
Content-Type: application/json
No Request Body:
{
"officeId": 1,
"clientId": 1,
"resourceId": 1
}
Savings Account Transactions:
Transactions possible on a savings account.
Field Descriptions |
| transactionDate |
| The date of the transaction. |
| transactionAmount |
| The amount of the transaction. |
Retrieve Savings Account Transaction 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 Requests:
savingsaccounts/1/transactions/template
GET https://Domain Name/api/v1/savingsaccounts/{accountId}/transactions/template
{
"accountId": 1,
"accountNo": "000000001",
"date": [
2013,
5,
27
],
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"paymentTypeOptions": [
{
"id": 14,
"name": "Wire Transfer",
"position": 0
},
{
"id": 13,
"name": "Cash",
"position": 1
}
]
}
Retrieve Savings Account Transaction:
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 Requests:
savingsaccounts/1/transactions/1
GET https://Domain Name/api/v1/savingsaccounts/{accountId}/transactions/{transactionId}
{
"id": 1,
"transactionType": {
"id": 2,
"code": "savingsAccountTransactionType.withdrawal",
"value": "Withdrawal",
"deposit": false,
"withdrawal": true,
"interestPosting": false,
"feeDeduction": false
},
"accountId": 1,
"accountNo": "000000001",
"date": [
2013,
8,
7
],
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"inMultiplesOf": 0,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"paymentDetailData": {
"id": 62,
"paymentType": {
"id": 11,
"name": "cash"
},
"accountNumber": "",
"checkNumber": "",
"routingCode": "",
"receiptNumber": "",
"bankNumber": ""
},
"amount": 5000,
"runningBalance": 0,
"reversed": true
}
Deposit Transaction
POST https://Domain Name/api/v1/savingsaccounts/{accountsId}/transactions?command=deposit
POST savingsaccounts/1/transactions?command=deposit
Content-Type: application/json
No Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"transactionDate": "27 May 2013",
"transactionAmount": "500",
"paymentTypeId": "14",
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
{
"officeId": 1,
"clientId": 2,
"savingsId": 1,
"resourceId": 47,
"changes": {
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
}
Withdrawal Transaction
POST https://Domain Name/api/v1/savingsaccounts/{accountsId}/transactions?command=withdrawal
POST savingsaccounts/1/transactions?command=withdrawal
Content-Type: application/json
No Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"transactionDate": "27 May 2013",
"transactionAmount": "500",
"paymentTypeId": "14",
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
{
"officeId": 1,
"clientId": 2,
"savingsId": 1,
"resourceId": 48,
"changes": {
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
}
Adjust Transaction
This command modifies the given transaction.
POST https://Domain Name/api/v1/savingsaccounts/{accountsId}/transactions/{transactionId}?command=modify
POST savingsaccounts/1/transactions/1?command=modify
Content-Type: application/json
No Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"transactionDate": "27 May 2013",
"transactionAmount": "500",
"paymentTypeId": "14",
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
{
"officeId": 1,
"clientId": 2,
"savingsId": 1,
"resourceId": 48,
"changes": {
"accountNumber": "acc123",
"checkNumber": "che123",
"routingCode": "rou123",
"receiptNumber": "rec123",
"bankNumber": "ban123"
}
}
Undo transaction
This command reverses the given transaction.
POST https://Domain Name/api/v1/savingsaccounts/{accountsId}/transactions/{transactionId}?command=undo
POST savingsaccounts/1/transactions/1?command=undo
Content-Type: application/json
No Request Body:
{
}
{
"officeId": 1,
"clientId": 2,
"savingsId": 1,
"resourceId": 1
}
Savings Charges
Its typical for MFIs to add maintenance and operating charges. They can be either Fees or Penalties.
Savings Charges are instances of Charges and represent either fees and penalties for savings products. Refer Charges for documentation of the various properties of a charge, Only additional properties ( specific to the context of a Charge being associated with a Savings account) are described here
Field Descriptions |
| amountPaid |
| The Total amount which has been paid for this Charge |
| amountWaived |
| The Total amount that has been waived for this Charge |
| amountWrittenOff |
| Total amount written off from this Charge |
| amountOutstanding |
| The Total outstanding amount for this Charge |
List Savings Charges
Example Requests:
savingsaccounts/1/charges
savingsaccounts/1/charges?fields=name,amountOrPercentage
GET https://DomainName/api/v1/savingsaccounts/{accountId}/charges
[
{
"id": 1,
"chargeId": 3,
"accountId": 57,
"name": "Savings account maintenance fee",
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"percentage": 0,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 100,
"amountOrPercentage": 100,
"penalty": false
},
{
"id": 2,
"chargeId": 4,
"accountId": 57,
"name": "Pass book Fee",
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"dueDate": [
2013,
3,
29
],
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"percentage": 0,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 100,
"amountOrPercentage": 100,
"penalty": false
},
{
"id": 9,
"chargeId": 4,
"accountId": 57,
"name": "Withdrawal fee percentage",
"chargeTimeType": {
"id": 5,
"code": "chargeTimeType.withdrawalFee",
"value": "Withdrawal Fee"
},
"chargeCalculationType": {
"id": 2,
"code": "chargeCalculationType.percent.of.amount",
"value": "% Amount"
},
"percentage": 0.25,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 0,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 0,
"amountOrPercentage": 0.25,
"penalty": false
},
{
"id": 10,
"chargeId": 6,
"accountId": 57,
"name": "Annual fee - INR",
"chargeTimeType": {
"id": 6,
"code": "chargeTimeType.annualFee",
"value": "Annual Fee"
},
"feeOnMonthDay": [
10,
9
],
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"percentage": 0,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 50,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 50,
"amountOrPercentage": 50,
"penalty": false
}
]
Retrieve Savings Charges 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:
savingsaccounts/1/charges/template
GET https://DomainName/api/v1/savingsaccounts/{accountId}/charges/template
{
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"chargeOptions": [
{
"id": 2,
"name": "Passbook Fee",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
}
},
{
"id": 3,
"name": "Chequebook fee",
"active": true,
"penalty": true,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 1,
"chargeTimeType": {
"id": 2,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeAppliesTo": {
"id": 1,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
}
},
{
"id": 6,
"name": "Annual fee",
"active": true,
"penalty": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 50,
"chargeTimeType": {
"id": 6,
"code": "chargeTimeType.annualFee",
"value": "Annual Fee"
},
"chargeAppliesTo": {
"id": 2,
"code": "chargeAppliesTo.savings",
"value": "Savings"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"chargePaymentMode": {
"id": 0,
"code": "chargepaymentmode.regular",
"value": "Regular"
}
}
],
"penalty": false
}
Retrieve a Savings account Charge
Example Requests:
/savingsaccounts/1/charges/5
/savingsaccounts/1/charges/5?fields=name,amountOrPercentage
GET https://DomainName/api/v1/savingsaccounts/{accountId}/charges/{savingsAccountChargeId}
{
"id": 1,
"chargeId": 1,
"name": "Passbook fee",
"chargeTimeType": {
"id": 1,
"code": "chargeTimeType.specifiedDueDate",
"value": "Specified due date"
},
"chargeCalculationType": {
"id": 1,
"code": "chargeCalculationType.flat",
"value": "Flat"
},
"percentage": 0,
"amountPercentageAppliedTo": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"amount": 100,
"amountPaid": 0,
"amountWaived": 0,
"amountWrittenOff": 0,
"amountOutstanding": 100,
"amountOrPercentage": 100,
"penalty": false
}
Create a Savings account Charge
Mandatory Fields
for Savings account Charges |
| chargeId, amount |
Mandatory Fields
for Savings account Charges of Specified due date type |
| chargeId, amount, dueDate, dateFormat, locale |
Mandatory Fields
for Savings account Charges of Annual fee type |
| chargeId, amount, feeOnMonthDay, monthDayFormat, locale |
POST https://DomainName/api/v1/savingsaccounts/{accountId}/charges
POST /savingsaccounts/1/charges
Content-Type: application/json
Request Body:
{
"chargeId": "2",
"locale": "en",
"amount": "100",
"dateFormat": "dd MMMM yyyy",
"dueDate": "29 April 2013"
}
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 6
}
POST /savingsaccounts/1/charges
Content-Type: application/json
Request Body:
{
"chargeId": "2",
"locale": "en",
"amount": "25",
"monthDayFormat": "dd MMMM",
"feeOnMonthDay": "09 October"
}
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 7
}
Update a Savings account Charge
Currently Savings account Charges may be updated only if the Savings account is not yet approved.
PUT https://DomainName/api/v1/savingsaccounts/{accountId}/charges/{savingsAccountChargeId}
PUT savingsaccounts/1/charges/6
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"amount": "60",
"dueDate": "27 March 2013"
}
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 6,
"changes": {
"dueDate": "27 March 2013",
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"amount": 60.0
}
}
Delete a Savings account Charge
Note:Currently, A Savings account Charge may only be removed from Savings that are not yet approved.
DELETE https://DomainName/api/v1/savingsaccounts/{accountId}/charges/{savingsAccountChargeId}
DELETE savingsaccounts/1/charges/2
Content-Type: application/json
No Request Body:
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 2
}
Pay a Savings account Charge
A charge will be paid when savings account is active and having sufficient balance.
POST https://DomainName/api/v1/savingsaccounts/{accountId}/charges/{savingsAccountChargeId}?command=paycharge
POST savingsaccounts/1/charges/2?command=paycharge
Content-Type: application/json
Request Body:
{
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"amount": "60",
"dueDate": "12 September 2013"
}
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 2
}
Waive off a Savings account Charge
Outstanding charge amount will be waived off.
POST https://DomainName/api/v1/savingsaccounts/{accountId}/charges/{savingsAccountChargeId}?command=waive
POST savingsaccounts/1/charges/2?command=waive
Content-Type: application/json
No Request Body:
{
"officeId": 1,
"clientId": 1,
"savingsId": 1,
"resourceId": 2
}
Account Transfers:
Ability to be able to transfer monetary funds from one account to another.
Note: At present only savings account to savings account transfers are supported.
Mandatory Parameters |
| fromOfficeId |
| The id of the office/branch from which the transfer is made. |
| fromClientId |
| The id of the client from which the transfer is made. |
| fromAccountType |
| The type of account from which the transfer is made. 1=Loan Account, 2=Savings Account |
| fromAccountId |
| The id of the account from which the transfer is made. |
| toOfficeId |
| The id of the office/branch to which the transfer is made. |
| toClientId |
| The id of the client to which the transfer is made. |
| toAccountType |
| The type of account to which the transfer is made. 1=Loan Account, 2=Savings Account |
| toAccountId |
| The id of the account to which the transfer is made. The accouont must be active and must have the same currency as that of the selected fromAccountId. |
| transferDate |
| The date of the transfer. Requires dateFormat and locale parameters. |
| transferAmount |
| The amount of the transfer. Requires locale parameter. |
| transferDescription |
| Description of the transfer itself. |
Retrieve Account Transfer 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 Requests:
accounttransfers/template?fromAccountType=2&fromOfficeId=1
accounttransfers/template?fromAccountType=2&fromOfficeId=1&fromClientId=1
accounttransfers/template?fromClientId=1&fromAccountType=2&fromAccountId=1
GET https://Domain Name/api/v1/accounttransfers/template?fromAccountType=2&fromOfficeId=1
{
"transferAmount": 0,
"transferDate": [
2013,
8,
15
],
"fromOffice": {
"id": 1,
"name": "HO",
"nameDecorated": "HO",
"externalId": "1",
"openingDate": [
2009,
1,
1
],
"hierarchy": "."
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromOfficeOptions": [
{
"id": 1,
"name": "HO",
"nameDecorated": "HO"
},
{
"id": 2,
"name": "Branch 1",
"nameDecorated": "....Branch 1"
}
],
"fromClientOptions": [
{
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
{
"id": 3,
"displayName": "Third client",
"officeId": 1,
"officeName": "HO"
}
],
"fromAccountTypeOptions": [
{
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
}
],
"toOfficeOptions": [
{
"id": 1,
"name": "HO",
"nameDecorated": "HO"
},
{
"id": 2,
"name": "Branch 1",
"nameDecorated": "....Branch 1"
}
],
"toAccountTypeOptions": [
{
"id": 1,
"code": "accountType.loan",
"value": "Loan Account"
},
{
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
}
]
}
GET https://Domain Name/api/v1/accounttransfers/template?fromAccountType=2&fromOfficeId=1&fromClientId=1
{
"transferAmount": 0,
"transferDate": [
2013,
8,
15
],
"fromOffice": {
"id": 1,
"name": "HO",
"nameDecorated": "HO",
"externalId": "1",
"openingDate": [
2009,
1,
1
],
"hierarchy": "."
},
"fromClient": {
"id": 1,
"accountNo": "000000001",
"status": {
"id": 300,
"code": "clientStatusType.active",
"value": "Active"
},
"active": true,
"activationDate": [
2013,
3,
1
],
"fullname": "Small shop",
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO",
"groups": []
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromOfficeOptions": [
{
"id": 1,
"name": "HO",
"nameDecorated": "HO"
},
{
"id": 2,
"name": "Branch 1",
"nameDecorated": "....Branch 1"
}
],
"fromClientOptions": [
{
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
{
"id": 3,
"displayName": "Third client",
"officeId": 1,
"officeName": "HO"
}
],
"fromAccountTypeOptions": [
{
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
}
],
"fromAccountOptions": [
{
"id": 1,
"accountNo": "000000001",
"clientId": 1,
"clientName": "Small shop",
"productId": 1,
"productName": "Passbook",
"fieldOfficerId": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
},
{
"id": 3,
"accountNo": "000000003",
"clientId": 1,
"clientName": "Small shop",
"productId": 2,
"productName": "Shilling product",
"fieldOfficerId": 0,
"currency": {
"code": "KES",
"name": "Kenyan Shilling",
"decimalPlaces": 0,
"inMultiplesOf": 0,
"displaySymbol": "KSh",
"nameCode": "currency.KES",
"displayLabel": "Kenyan Shilling (KSh)"
}
}
],
"toOfficeOptions": [
{
"id": 1,
"name": "HO",
"nameDecorated": "HO"
},
{
"id": 2,
"name": "Branch 1",
"nameDecorated": "....Branch 1"
}
],
"toAccountTypeOptions": [
{
"id": 1,
"code": "accountType.loan",
"value": "Loan Account"
},
{
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
}
]
}
GET https://Domain Name/api/v1/accounttransfers/template?fromClientId=1&fromAccountType=2&fromAccountId=1
{
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"transferAmount": 0,
"transferDate": [
2013,
8,
15
],
"fromOffice": {
"id": 1,
"name": "HO",
"nameDecorated": "HO",
"externalId": "1",
"openingDate": [
2009,
1,
1
],
"hierarchy": "."
},
"fromClient": {
"id": 1,
"accountNo": "000000001",
"status": {
"id": 300,
"code": "clientStatusType.active",
"value": "Active"
},
"active": true,
"activationDate": [
2013,
3,
1
],
"fullname": "Small shop",
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO",
"groups": []
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromAccount": {
"id": 1,
"accountNo": "000000001",
"clientId": 1,
"clientName": "Small shop",
"productId": 1,
"productName": "Passbook",
"fieldOfficerId": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
},
"fromOfficeOptions": [
{
"id": 1,
"name": "HO",
"nameDecorated": "HO"
},
{
"id": 2,
"name": "Branch 1",
"nameDecorated": "....Branch 1"
}
],
"fromClientOptions": [
{
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
{
"id": 3,
"displayName": "Third client",
"officeId": 1,
"officeName": "HO"
}
],
"fromAccountTypeOptions": [
{
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
}
],
"fromAccountOptions": [
{
"id": 1,
"accountNo": "000000001",
"clientId": 1,
"clientName": "Small shop",
"productId": 1,
"productName": "Passbook",
"fieldOfficerId": 0,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
}
},
{
"id": 3,
"accountNo": "000000003",
"clientId": 1,
"clientName": "Small shop",
"productId": 2,
"productName": "Shilling product",
"fieldOfficerId": 0,
"currency": {
"code": "KES",
"name": "Kenyan Shilling",
"decimalPlaces": 0,
"inMultiplesOf": 0,
"displaySymbol": "KSh",
"nameCode": "currency.KES",
"displayLabel": "Kenyan Shilling (KSh)"
}
}
],
"toOfficeOptions": [
{
"id": 1,
"name": "HO",
"nameDecorated": "HO"
},
{
"id": 2,
"name": "Branch 1",
"nameDecorated": "....Branch 1"
}
],
"toAccountTypeOptions": [
{
"id": 1,
"code": "accountType.loan",
"value": "Loan Account"
},
{
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
}
]
}
Create new Transfer
Ability to create new transfer of monetary funds from one account to another.
POST https://Domain Name/api/v1/accounttransfers
POST accounttransfers/
Content-Type: application/json
No Request Body:
{
"fromOfficeId": 1,
"fromClientId": 1,
"fromAccountType": 2,
"fromAccountId": 1,
"toOfficeId": 1,
"toClientId": 1,
"toAccountType": 2,
"toAccountId": 2,
"dateFormat": "dd MMMM yyyy",
"locale": "en",
"transferDate": "01 August 2011",
"transferAmount": "112.45",
"transferDescription": "A description of the transfer"
}
{
"savingsId": 1,
"resourceId": 1
}
List account transfers
Example Requests:
accounttransfers
GET https://Domain Name/api/v1/accounttransfers
{
"totalFilteredRecords": 4,
"pageItems": [
{
"id": 1,
"reversed": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"transferAmount": 200,
"transferDate": [
2013,
4,
1
],
"transferDescription": "pay off loan from savings.",
"fromOffice": {
"id": 1,
"name": "HO"
},
"fromClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromAccount": {
"id": 1,
"accountNo": "000000001"
},
"toOffice": {
"id": 1,
"name": "HO"
},
"toClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"toAccountType": {
"id": 1,
"code": "accountType.loan",
"value": "Loan Account"
},
"toAccount": {
"id": 1,
"accountNo": "000000001"
}
},
{
"id": 2,
"reversed": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"transferAmount": 112.45,
"transferDate": [
2013,
6,
1
],
"transferDescription": "A description of the transfer",
"fromOffice": {
"id": 1,
"name": "HO"
},
"fromClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromAccount": {
"id": 1,
"accountNo": "000000001"
},
"toOffice": {
"id": 1,
"name": "HO"
},
"toClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"toAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"toAccount": {
"id": 3,
"accountNo": "000000003"
}
},
{
"id": 3,
"reversed": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"transferAmount": 112.45,
"transferDate": [
2013,
6,
1
],
"transferDescription": "A description of the transfer",
"fromOffice": {
"id": 1,
"name": "HO"
},
"fromClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromAccount": {
"id": 1,
"accountNo": "000000001"
},
"toOffice": {
"id": 1,
"name": "HO"
},
"toClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"toAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"toAccount": {
"id": 3,
"accountNo": "000000003"
}
},
{
"id": 4,
"reversed": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"transferAmount": 112.45,
"transferDate": [
2013,
6,
1
],
"transferDescription": "A description of the transfer",
"fromOffice": {
"id": 1,
"name": "HO"
},
"fromClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromAccount": {
"id": 1,
"accountNo": "000000001"
},
"toOffice": {
"id": 1,
"name": "HO"
},
"toClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"toAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"toAccount": {
"id": 3,
"accountNo": "000000003"
}
}
]
}
Retrieve account transfer:
Example Requests :
accounttransfers/1
GET https://DomainName/api/v1/accounttransfers/{transferId}
{
"id": 1,
"reversed": false,
"currency": {
"code": "USD",
"name": "US Dollar",
"decimalPlaces": 2,
"displaySymbol": "$",
"nameCode": "currency.USD",
"displayLabel": "US Dollar ($)"
},
"transferAmount": 200,
"transferDate": [
2013,
4,
1
],
"transferDescription": "pay off loan from savings.",
"fromOffice": {
"id": 1,
"name": "HO"
},
"fromClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"fromAccountType": {
"id": 2,
"code": "accountType.savings",
"value": "Savings Account"
},
"fromAccount": {
"id": 1,
"accountNo": "000000001"
},
"toOffice": {
"id": 1,
"name": "HO"
},
"toClient": {
"id": 1,
"displayName": "Small shop",
"officeId": 1,
"officeName": "HO"
},
"toAccountType": {
"id": 1,
"code": "accountType.loan",
"value": "Loan Account"
},
"toAccount": {
"id": 1,
"accountNo": "000000001"
}
}
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 plug-in called stretchydatatables (which in turn uses this datatables resource) to provide a pretty flexible CRUD (Create, Read, Update, Delete) User Interface.
Create Data Table
Create a new data table and registers it with the Mifos X Core application table.
Field Descriptions |
| Mandatory - datatableName |
| The name of the Data Table. |
| Mandatory - apptableName |
Application table name. Must be one of the following:
|
| Mandatory - columns |
| An array of columns in the new Data Table. |
Field Descriptions - columns |
| Mandatory - name |
| Name of the created column. Can contain only alphanumeric characters, underscores and spaces, but cannot start with a number. Cannot start or end with an underscore or space. |
| Mandatory - type |
Column type. Must be one of the following:
|
| Mandatory [type = Dropdown] - code |
| Used in Code Value fields. Column name becomes: code_cd_name. Mandatory if using type Dropdown, otherwise an error is returned. |
| Optional - mandatory |
| Determines whether this column must have a value in every entry. Optional, defaults to false. |
| Mandatory [type = String] - length |
| Length of the text field. Mandatory if type String is used, otherwise an error is returned. |
POST https://DomainName/api/v1/datatables
POST https://DomainName/api/v1/datatables
Content-Type: application/json
Request Body:
{
"datatableName": "extra_client_details",
"apptableName": "m_client",
"columns": [
{
"name": "Gender",
"type": "Dropdown",
"code": "Gender"
},
{
"name": "Some Decimal",
"type": "Decimal",
"mandatory": true
},
{
"name": "Birth Date",
"type": "Date"
},
{
"name": "Question 2",
"type": "String",
"length": 100,
"mandatory": false
}
]
}
{
"resourceIdentifier": "extra_client_details"
}
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://DomainName/api/v1/datatables
[
{
"applicationTableName": "m_client",
"registeredTableName": "extra_client_details",
"columnHeaderData": [
{
"columnName": "client_id",
"columnType": "bigint",
"columnLength": 0,
"columnDisplayType": "INTEGER",
"isColumnNullable": false,
"isColumnPrimaryKey": true,
"columnValues": []
},
{
"columnName": "Gender_cd_Question",
"columnType": "int",
"columnLength": 0,
"columnDisplayType": "INTEGER",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Some Decimal",
"columnType": "decimal",
"columnLength": 0,
"columnDisplayType": "DECIMAL",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Birth Date",
"columnType": "date",
"columnLength": 0,
"columnDisplayType": "DATE",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
}
]
}
]
Retrieve Data Table Details
Lists a registered data table details and the Mifos X Core application table they are registered to.
GET https://DomainName/api/v1/datatables/{datatable}
{
"applicationTableName": "m_client",
"registeredTableName": "extra_client_details",
"columnHeaderData": [
{
"columnName": "client_id",
"columnType": "bigint",
"columnLength": 0,
"columnDisplayType": "INTEGER",
"isColumnNullable": false,
"isColumnPrimaryKey": true,
"columnValues": []
},
{
"columnName": "Gender_cd_Question",
"columnType": "int",
"columnLength": 0,
"columnDisplayType": "INTEGER",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Some Decimal",
"columnType": "decimal",
"columnLength": 0,
"columnDisplayType": "DECIMAL",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Birth Date",
"columnType": "date",
"columnLength": 0,
"columnDisplayType": "DATE",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
}
]
}
Update Data Table
Modifies fields of a data table. If the apptableName parameter is passed, data table is deregistered and registered with the new application table.
Field Descriptions |
| Optional - apptableName |
Application table name. Only necessary if changing the application table this Data Table is registered to. Must be one of the following:
|
| Optional - dropColumns |
| An array of columns to be deleted from the Data Table. |
| Optional - addColumns |
| An array of columns to be added to the Data Table. |
| Optional - changeColumns |
| An array of columns to be changed in the Data Table. |
Field Descriptions - dropColumns |
| Mandatory - name |
| Requires a full name of the deleted column to be provided. |
Field Descriptions - addColumns |
| Mandatory - name |
| Name of the created column. Can contain only alphanumeric characters, underscores and spaces, but cannot start with a number. Cannot start or end with an underscore or space. |
| Mandatory - type |
Column type. Must be one of the following:
|
| Mandatory [type = Dropdown] - code |
| Used in Code Value fields. Column name becomes: code_cd_name. Mandatory if using type Dropdown, otherwise an error is returned. |
| Optional - mandatory |
| Determines whether this column must have a value in every entry. Optional, defaults to false. |
| Mandatory [type = String] - length |
| Length of the text field. Mandatory if type String is used, otherwise an error is returned. |
| Optional - after |
| Only used when re-ordering Data Table columns. Requires a full column name to be provided. |
Field Descriptions - changeColumns |
| Mandatory - name |
| Name of the created column. Can contain only alphanumeric characters, underscores and spaces, but cannot start with a number. Cannot start or end with an underscore or space. |
| Optional - newName |
| New name of the created column. Can contain only alphanumeric characters, underscores and spaces, but cannot start with a number. Cannot start or end with an underscore or space. |
| Mandatory [type = Dropdown] - code |
| Used in Code Value fields. Column name becomes: code_cd_name. Mandatory if using type Dropdown, otherwise an error is returned. |
| Optional [type = Dropdown] - newCode |
| Used in Code Value fields. Column name becomes: code_cd_name. Optional if using type Dropdown, otherwise an error is returned. |
| Optional - mandatory |
| Determines whether this column must have a value in every entry. Optional, defaults to false. |
| Mandatory [type = String] - length |
| Length of the text field. Mandatory if type String is used, otherwise an error is returned. |
| Optional - after |
| Only used when re-ordering Data Table columns. Requires a full column name to be provided. |
PUT https://DomainName/api/v1/datatables/{datatables}
PUT https://DomainName/api/v1/datatables/extra_client_details
Content-Type: application/json
Request Body:
{
"apptableName": "m_client",
"dropColumns": [
{
"name": "Gender_cd_Question"
}
],
"addColumns": [
{
"name": "Question",
"type": "Dropdown",
"code": "Gender",
"mandatory": true
},
{
"name": "Some Number",
"type": "Number",
"after": "Some Field"
}
],
"changeColumns": [
{
"name": "Question",
"newName": "Question 2",
"mandatory": true,
"code": "Gender",
"newCode": "Gender2"
}
]
}
{
"resourceIdentifier": "extra_client_details"
}
Delete Data Table
Deletes a data table and deregisters it from the Mifos X Core application table.
DELETE https://DomainName/api/v1/datatables/{datatables}
DELETE https://DomainName/api/v1/datatables/extra_client_details
Content-Type: application/json
No Request Body
{
"resourceIdentifier": "extra_client_details"
}
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://DomainName/api/v1/datatables/register/{datatable}/{apptable}
POST datatables/register/extra_client_details/m_client
Content-Type: application/json
Request Body:
{}
{
"resourceIdentifier": "extra_client_details"
}
Deregister Data Table
Deregisters a data table. It will no longer be available through the API.
POST https://DomainName/api/v1/datatables/deregister/{datatable}
POST datatables/deregister/extra_client_details
Content-Type: application/json
Request Body:
{}
{
"resourceIdentifier": "extra_client_details"
}
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://DomainName/api/v1/datatables/{datatable}/{apptableId}
POST datatables/extra_client_details/1
Content-Type: application/json
Request Body:
{
"Business Description": "Livestock sales",
"Comment": "First comment made",
"Education_cv": "Primary",
"Gender_cd": "6",
"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, defaults to false
- If 'true' an optimised JSON format is returned suitable for tabular display of data. This format is used by the default data tables UI functionality.
Example Requests:
datatables/extra_client_details/1
datatables/extra_family_details/1?order=`Date of Birth` desc
datatables/extra_client_details/1?genericResultSet=true
GET https://DomainName/api/v1/datatables/{datatable}/{apptableId}?genericResultSet=true
{
"columnHeaders": [
{
"columnName": "client_id",
"columnType": "bigint",
"columnLength": 0,
"columnDisplayType": "INTEGER",
"isColumnNullable": false,
"isColumnPrimaryKey": true,
"columnValues": []
},
{
"columnName": "Business Description",
"columnType": "varchar",
"columnLength": 100,
"columnDisplayType": "STRING",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Years in Business",
"columnType": "int",
"columnLength": 0,
"columnDisplayType": "INTEGER",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Gender_cd",
"columnType": "int",
"columnLength": 0,
"columnDisplayType": "CODELOOKUP",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": [
{
"id": 5,
"value": "option.Male"
},
{
"id": 6,
"value": "option.Female"
}
]
},
{
"columnName": "Education_cv",
"columnType": "varchar",
"columnLength": 60,
"columnDisplayType": "CODEVALUE",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": [
{
"id": 9,
"value": "Primary"
},
{
"id": 10,
"value": "Secondary"
},
{
"id": 11,
"value": "University"
}
]
},
{
"columnName": "Next Visit",
"columnType": "date",
"columnLength": 0,
"columnDisplayType": "DATE",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Highest Rate Paid",
"columnType": "decimal",
"columnLength": 0,
"columnDisplayType": "DECIMAL",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Comment",
"columnType": "text",
"columnLength": 65535,
"columnDisplayType": "TEXT",
"isColumnNullable": true,
"isColumnPrimaryKey": false,
"columnValues": []
}
],
"data": [
{
"row": [
"1",
"Livestock sales",
"5",
"6",
"Primary",
"2012-10-01",
"8.500000",
"First\tcomment made"
]
}
]
}
Update Entry in Data Table (One to One)
Updates the row (if it exists) of the data table.
PUT https://DomainName/api/v1/datatables/{datatable}/{apptableId}
PUT datatables/extra_client_details/1
Content-Type: application/json
Request Body:
{
"Business Description": "Livestock sales updated",
}
{
"resourceId": 1,
"changes": {
"Business Description": "Livestock sales updated"
}
}
Update Entry in Data Table (One to Many)
Updates the row (if it exists) of the data table.
PUT https://DomainName/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://DomainName/api/v1/datatables/{datatable}/{apptableId}
DELETE datatables/extra_client_details/1
Content-Type: application/json
Request Body:
{}
{
"resourceId": 1
}
Delete Entry in Datatable (One to Many)
Deletes the entry (if it exists) for data tables that are one to many with the application table.
DELETE https://DomainName/api/v1/datatables/{datatable}/{apptableId}/{datatableId}
DELETE datatables/extra_family_details/1/2
Content-Type: application/json
Request Body:
{}
{
"resourceId": 1
}
Notes
Notes API allows to enter notes for supported resources.
Field Descriptions |
| note |
| A simple text note created for supported resources. |
Supported Resources |
|
Client
Loan Group Savings Account |
Add a Resource Note
Adds a new note to a supported resource.
Mandatory Fields |
| note |
Example Requests:
clients/1/notes
groups/1/notes
POST https://DomainName/api/v1/{resource}/{resourceId}/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 Resource's Notes
Note: Notes are returned in descending createOn order.
Example Requests:
clients/2/notes
groups/2/notes?fields=note,createdOn,createdByUsername
GET https://DomainName/api/v1/{resource}/{resourceId}/notes
[
{
"id": 2,
"clientId": 1,
"noteType": {
"id": 100,
"code": "noteType.client",
"value": "Client note"
},
"note": "First note edited",
"createdById": 1,
"createdByUsername": "mifos",
"createdOn": 1342498505000,
"updatedById": 1,
"updatedByUsername": "mifos",
"updatedOn": 1342498517000
}
]
Retrieve a Resource Note
Example Requests:
clients/1/notes/76
groups/1/notes/20
clients/1/notes/76?fields=note,createdOn,createdByUsername
groups/1/notes/20?fields=note,createdOn,createdByUsername
GET https://DomainName/api/v1/{resource}/{resourceId}/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 Resource Note
PUT https://DomainName/api/v1/{resource}/{resourceId}/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."
}
}
Delete a Resource Note
DELETE https://DomainName/api/v1/{resource}/{resourceId}/notes/{noteId}
DELETE clients/1/notes/76
Content-Type: application/json
No Request Body:
{
"resourceId": 76
}
Documents
Multiple Documents (a combination of a name, description and a file) may be attached to different Entities like Clients, Groups, Staff, Loans, Savings and Client Identifiers in the system
Note: The currently allowed Entities are
- Clients: URL Pattern as clients
- Staff: URL Pattern as staff
- Loans: URL Pattern as loans
- Savings: URL Pattern as savings
- Client Identifiers: URL Pattern as client_identifiers
- Groups: URL Pattern as groups
Field Descriptions |
| parentEntityType |
| The type of the Entity with which this document is associated |
| parentEntityId |
| The ID of the entity (client, loan etc) with which this document is associated |
| name |
| User Defined name for the document, need not be the same as the name of the file associated with the document |
| fileName |
| The name of the file associated with this document |
| size |
| The size (in bytes) of the file associated with this document |
| type |
| Mime Type of the file associated with this document |
| description |
| A description of this document |
List documents
Example Requests:
clients/1/documents
client_identifiers/1/documents
loans/1/documents?fields=name,description
GET https://DomainName/api/v1/{entityType}/{entityId}/documents
[
{
"id": 1,
"parentEntityType": "clients",
"parentEntityId": 1,
"name": "Client Details Form ",
"fileName": "CGAP.pdf",
"size": 5246719,
"type": "application/pdf",
"description": "A signed form signed by new member"
}
]
Retrieve a Document
Example Requests:
clients/1/documents/1
loans/1/documents/1
client_identifiers/1/documents/1?fields=name,description
GET https://DomainName/api/v1/documents/{clientId}
{
"id": 1,
"parentEntityType": "clients",
"parentEntityId": 1,
"name": "Client Details Form ",
"fileName": "CGAP.pdf",
"size": 5246719,
"type": "application/pdf",
"description": "A signed form signed by new member"
}
Create a Document
Note: A document is created using a Multi-part form upload
Body Parts |
| name |
| Name or summary of the document |
| description |
| Description of the document |
| file |
| The file to be uploaded |
Mandatory Fields |
| file and description |
POST https://DomainName/api/v1/{entityType}/{entityId}/documents
POST clients/1/documents
Content-Type: multipart/form-data
Request Body:
Not Shown (multi-part form data)
{
"resourceId":3,
"resourceIdentifier":"3"
}
Update a Document
Note: A document is updated using a Multi-part form upload
Body Parts |
| name |
| Name or summary of the document |
| description |
| Description of the document |
| file |
| The file to be uploaded |
PUT https://DomainName/api/v1/{entityType}/{entityId}/documents/{documentId}
PUT clients/1/documents/1
Content-Type: multipart/form-data
Request Body:
Not Shown (multi-part form data)
{
"resourceId":3,
"changes":{},
"resourceIdentifier":"3"
}
Retrieve Binary File associated with Document
Request used to download the file associated with the document
Example Requests:
clients/1/documents/1/attachment
loans/1/documents/1/attachment
GET https://DomainName/api/v1/{entityType}/{entityId}/documents/{documentId}/attachment
Not Shown: The corresponding Binary file
Remove a Document
DELETE https://DomainName/api/v1/{entityType}/{entityId}/documents/{documentId}
DELETE clients/1/documents/1
Content-Type: application/json
No Request Body:
{
"resourceId":1,
"changes":{},
"resourceIdentifier":"1"
}
DELETE https://DomainName/api/v1/{entityType}/{entityId}/documents/{documentId}
DELETE loans/1/documents/1
Content-Type: application/json
No Request Body:
{
"resourceId":1,
"changes":{},
"resourceIdentifier":"1"
}
Reports
Non-core reports can be added, updated and deleted.
Core reports (supplied at installation/upgrade time) can only have their "useReport" updated. "useReport" is used, for example, in the reference UI report page to 'show'/'not show' reports. Reports that have useReport set to false can still be run. Reports only used for workflow purposes are examples of reports that would have their useReport set to false.
Placeholders can be put in the reportSql to act as parameters. They have the format ${paramName}.
The runreports api will translate the value of any query parameter beginning R_ with the equivalent placeholder.
e.g. query parameter R_myName=john will replace ${myName} with john
There is a special 'automatic' placeholder ${currentUserHierarchy} - if this is included in reportSql
it gets replaced by the requesting users' office hierarchy value. This enables data scoping.
Usage example "where o.hierarchy like CONCAT('${currentUserHierarchy}', '%')"
Note:
The reports api allows parameters (not just placeholders in reportSql) to be associated with reports.
These associated parameters are only required to allow the reference UI reporting functionality implement
user-friendly parameter input.
Retrieve Report 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:
reports/template
GET https://DomainName/api/v1/reports/template
{
"allowedReportTypes": [
"Table",
"Pentaho",
"Chart"
],
"allowedReportSubTypes": [
"Bar",
"Pie"
],
"allowedParameters": [
{
"id": 1,
"parameterName": "startDateSelect"
},
{
"id": 2,
"parameterName": "endDateSelect"
},
{
"id": 3,
"parameterName": "obligDateTypeSelect"
},
{
"id": 5,
"parameterName": "OfficeIdSelectOne"
},
{
"id": 6,
"parameterName": "loanOfficerIdSelectAll"
},
{
"id": 10,
"parameterName": "currencyIdSelectAll"
},
{
"id": 20,
"parameterName": "fundIdSelectAll"
},
{
"id": 25,
"parameterName": "loanProductIdSelectAll"
},
{
"id": 26,
"parameterName": "loanPurposeIdSelectAll"
},
{
"id": 100,
"parameterName": "parTypeSelect"
}
]
}
Create a Report
POST https://DomainName/api/v1/reports
POST reports
Content-Type: application/json
Request Body:
{
"reportName":"Completely New Report",
"reportType":"Table",
"reportSubType":"",
"reportCategory":"Loan",
"useReport":"false",
"description":"Just\nAn\nExample",
"reportSql":"select 'very good sql' as AComment",
"reportParameters":[{"id":"","parameterId":"5","reportParameterName":""},{"id":"","parameterId":"6","reportParameterName":""}]
}
{
"resourceId": 132
}
List Reports
Lists all reports and their parameters.
Example Request:
reports
GET https://DomainName/api/v1/reports
[
{
"id": 1,
"reportName": "Client Listing",
"reportType": "Table",
"reportCategory": "Client",
"description": "Individual Client Report\r\n\r\nLists the small number of defined fields on the client table. Would expect to copy this \n\nreport and add any \u0027one to one\u0027 additional data for specific tenant needs.\r\n\r\nCan be run for any size MFI but you\u0027d expect it only to be run within a branch for \n\nlarger ones. Depending on how many columns are displayed, there is probably is a limit of about 20/50k clients returned for html display (export to excel doesn\u0027t \n\nhave that client browser/memory impact).",
"coreReport": true,
"useReport": true,
"reportParameters": [
{
"id": 1,
"parameterId": 5,
"parameterName": "OfficeIdSelectOne"
}
]
},
{
"id": 2,
"reportName": "Client Loans Listing",
"reportType": "Table",
"reportCategory": "Client",
"description": "Individual Client Report\n\nPretty \n\nwide report that lists the basic details of client loans. \n\nCan be run for any size MFI but you\u0027d expect it only to be run within a branch for larger ones. \n\nThere is probably is a limit of about 20/50k clients returned for html display (export to excel doesn\u0027t have that client browser/memory impact).",
"coreReport": false,
"useReport": true,
"reportParameters": [
{
"id": 2,
"parameterId": 5,
"parameterName": "OfficeIdSelectOne"
},
{
"id": 3,
"parameterId": 6,
"parameterName": "loanOfficerIdSelectAll"
},
{
"id": 4,
"parameterId": 10,
"parameterName": "currencyIdSelectAll"
},
{
"id": 5,
"parameterId": 20,
"parameterName": "fundIdSelectAll"
},
{
"id": 6,
"parameterId": 25,
"parameterName": "loanProductIdSelectAll"
},
{
"id": 7,
"parameterId": 26,
"parameterName": "loanPurposeIdSelectAll"
}
]
},...
]
Retrieve a Report
Example Requests:
reports/1
reports/1?template=true
GET https://DomainName/api/v1/reports/{id}
{
"id": 1,
"reportName": "Client Listing",
"reportType": "Table",
"reportCategory": "Client",
"description": "Individual Client Report\r\n\r\nLists the small number of defined fields on the client table. Would expect to copy this \n\nreport and add any \u0027one to one\u0027 additional data for specific tenant needs.\r\n\r\nCan be run for any size MFI but you\u0027d expect it only to be run within a branch for \n\nlarger ones. Depending on how many columns are displayed, there is probably is a limit of about 20/50k clients returned for html display (export to excel doesn\u0027t \n\nhave that client browser/memory impact).",
"reportSql": "select \nconcat(repeat(\"..\", \n ((LENGTH(ounder.`hierarchy`) - LENGTH(REPLACE(ounder.`hierarchy`, \u0027.\u0027, \u0027\u0027)) - 1))), ounder.`name`) as \"Office/Branch\",\n c.account_no as \"Client Account No.\", \nc.display_name as \"Name\", \nr.enum_message_property as \"Status\",\nc.activation_date as \"Activation\", c.external_id as \"External Id\"\nfrom m_office o \njoin m_office ounder on ounder.hierarchy like concat(o.hierarchy, \u0027%\u0027)\nand ounder.hierarchy like concat(\u0027${currentUserHierarchy}\u0027, \u0027%\u0027)\njoin m_client c on c.office_id \u003d ounder.id\nleft join r_enum_value r on r.enum_name \u003d \u0027status_enum\u0027 and r.enum_id \u003d c.status_enum\nwhere o.id \u003d ${officeId}\norder by ounder.hierarchy, c.account_no",
"coreReport": true,
"useReport": true,
"reportParameters": [
{
"id": 1,
"parameterId": 5,
"parameterName": "OfficeIdSelectOne"
}
]
}
Update a Report
Only the useReport value can be updated for core reports.
PUT https://DomainName/api/v1/reports/{id}
PUT reports/129
Content-Type: application/json
Request Body:
{
"reportName": "New rpt name",
"reportParameters": [
{
"id": 194,
"parameterId": 5,
"reportParameterName": "m"
}
]
}
{
"resourceId": 129,
"changes": {
"reportName": "New rpt name",
"reportParameters": "[{\"id\":194,\"parameterId\":5,\"reportParameterName\":\"m\"}]"
}
}
Delete a Report
Only non-core reports can be deleted.
DELETE https://DomainName/api/v1/reports/{id}
DELETE reports/100
Content-Type: application/json
Request Body:
{}
{
"resourceId": 100
}
Run Reports
Running a Report
This resource allows you to run and receive output from pre-defined Mifos X reports.
Reports can also be used to provide data for searching and workflow functionality.
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 reference application uses a JQuery plugin called stretchyreporting which, itself, uses this reports resource to provide a pretty flexible reporting User Interface (UI).
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
- genericResultSet
- optional, defaults to true
- If 'true' an optimised JSON format is returned suitable for tabular display of data.
- If 'false' a simple JSON format is returned.
- 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.
- locale
- optional
- Any valid locale Ex: en_US, en_IN, fr_FR etc
- Only applies to Pentaho reports.
Example Requests:
runreports/Client%20Listing?R_officeId=1
runreports/Client%20Listing?R_officeId=1&exportCSV=true
runreports/OfficeIdSelectOne?R_officeId=1¶meterType=true
runreports/OfficeIdSelectOne?R_officeId=1¶meterType=true&exportCSV=true
runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=HTML&R_officeId=1
runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=XLS&R_officeId=1
runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=CSV&R_officeId=1
runreports/Expected%20Payments%20By%20Date%20-%20Formatted?R_endDate=2013-04-30&R_loanOfficerId=-1&R_officeId=1&R_startDate=2013-04-16&output-type=PDF&R_officeId=1
GET https://DomainName/api/v1/runreports/{reportName}
{
"columnHeaders": [
{
"columnName": "Office/Branch",
"columnType": "VARCHAR",
"isColumnNullable": false,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Client Account No.",
"columnType": "VARCHAR",
"isColumnNullable": false,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Name",
"columnType": "VARCHAR",
"isColumnNullable": false,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "Joined",
"columnType": "DATE",
"isColumnNullable": false,
"isColumnPrimaryKey": false,
"columnValues": []
},
{
"columnName": "External Id",
"columnType": "VARCHAR",
"isColumnNullable": false,
"isColumnPrimaryKey": false,
"columnValues": []
}
],
"data": [
{
"row": [
"Head Office",
"000000001",
"Petra Yton",
"2009-03-04",
"786YYH7"
]
},
{
"row": [
"Head Office",
"000000002",
"Keith(changed) Yton",
"2009-03-04",
null
]
},
{
"row": [
"Head Office",
"000000003",
"Jorge lastname",
"2013-02-05",
null
]
}
]
}
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 roles and permissions allowed.
POST https://DomainName/api/v1/authentication?username={username}&password={password}
POST authentication?username=mifos&password=password
Content-Type: application/json
No Request Body
Example response of autentication for user that is not linked with any staff.
{
"username": "mifos",
"userId": 1,
"base64EncodedAuthenticationKey": "bWlmb3M6cGFzc3dvcmQ=",
"authenticated": true,
"officeId": 1,
"officeName": "Head Office",
"roles": [
{
"id": 1,
"name": "Super user",
"description": "This role provides all application permissions."
}
],
"permissions": [
"ALL_FUNCTIONS"
]
}
Example response of autentication for user that is linked with a staff member and role.
{
"username": "mifos",
"userId": 1,
"base64EncodedAuthenticationKey": "bWlmb3M6cGFzc3dvcmQ=",
"authenticated": true,
"officeId": 1,
"officeName": "Head Office",
"staffId": 1,
"staffDisplayName": "Director, Program",
"organisationalRole": {
"id": 100,
"code": "staffOrganisationalRoleType.programDirector",
"value": "Program Director"
},
"roles": [
{
"id": 1,
"name": "Super user",
"description": "This role provides all application permissions."
}
],
"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/openMF/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://DomainName/api/v1/users
[
{
"id": 1,
"username": "mifos",
"officeId": 1,
"officeName": "Head Office",
"firstname": "App",
"lastname": "Administrator",
"email": "demomfi@mifos.org",
"selectedRoles": [
{
"id": 1,
"name": "Super user",
"description": "This role provides all application permissions."
}
]
}
]
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://DomainName/api/v1/users/template
{
"allowedOffices": [
{
"id": 1,
"name": "Head Office",
"nameDecorated": "Head Office"
}
],
"availableRoles": [
{
"id": 1,
"name": "Super user",
"description": "This role provides all application permissions."
}
]
}
Retrieve a User
Example Requests:
users/1
users/1?template=true
users/1?fields=username,officeName
GET https://DomainName/api/v1/users/{userId}
{
"id": 1,
"username": "mifos",
"officeId": 1,
"officeName": "Head Office",
"firstname": "App",
"lastname": "Administrator",
"email": "demomfi@mifos.org",
"availableRoles": [],
"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://DomainName/api/v1/users
POST users
Content-Type: application/json
Request body:
{
"username": "newuser",
"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://DomainName/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://DomainName/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://DomainName/api/v1/roles
[
{
"id": 1,
"name": "Super user",
"description": "This role provides all application permissions."
}
]
Retrieve a Role
Example Requests:
roles/1
roles/1?fields=name
GET https://DomainName/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://DomainName/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": 2}
Update a Role
PUT https://DomainName/api/v1/roles/{roleId}
PUT roles/1
Content-Type: application/json
Request body:
{
"description": "some description(changed)"
}
{
"resourceId": 1,
"changes": {
"description": "some description(changed)"
}
}
Retrieve a Role's Permissions
Example Requests:
roles/1/permissions
GET https://DomainName/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": "transaction_loan",
"code": "WRITEOFF_LOAN_CHECKER",
"entityName": "LOAN",
"actionName": "WRITEOFF",
"selected": false
}
]
}
Update a Role's Permissions
PUT https://DomainName/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.
There is no Mifos X functionality for creating or deleting permissions. Permissions come pre-installed.
Permissions are not updated, except in the case of enabling or disabling non-read transactions for Maker Checker functionality
List Application Permissions
Arguments
- makerCheckerable
- optional,
Values are true, false. Default is false.
If makerCheckerable=false or not supplied then a list of application permissions is returned. The "selected" attribute is always true in this case.
If makerCheckerable=true then the "selected" attribute shows whether the permission is enabled for Maker Check functionality.
Note: Each Mifos X transaction is associated with a permission.
Example Requests:
permissions
permissions?makerCheckerable=true
permissions?fields=grouping,code
GET https://DomainName/api/v1/permissions
[
{
"grouping": "authorisation",
"code": "READ_PERMISSION",
"entityName": "PERMISSION",
"actionName": "READ",
"selected": true
},
....
{
"grouping": "transaction_loan",
"code": "WRITEOFF_LOAN",
"entityName": "LOAN",
"actionName": "WRITEOFF",
"selected": true
}
]
Enable/Disable Permissions for Maker Checker
PUT https://DomainName/api/v1/permissions
PUT permissions
Content-Type: application/json
Request Body:
{
"permissions":{
"CREATE_GUARANTOR":true,
"CREATE_CLIENT":true
}
}
General Ledger Account
Ledger accounts represent an Individual account within an Organizations Chart
Of Accounts(COA) and are assigned a name and unique number by which they can
be identified.
All transactions relating to a company's assets, liabilities, owners' equity,
revenue and expenses are recorded against these accounts
Field Descriptions |
| name |
| The name of the account |
| glCode |
| The ledger code associated with the
Account These codes are mandatory and should be unique within an organization |
| disabled |
| A boolean flag that indicates whether an account is currently in use |
| type |
| Classifies the account into one of the following Types
Asset: represent the different types of economic resources owned or controlled by business, common examples of Asset accounts are cash, cash in bank, building, inventory, prepaid rent, goodwill, accounts receivable Liability: represent the different types of economic obligations by a business, such as accounts payable, bank loan, bonds payable Income: represent the company's gross earnings and common examples include Interest Income, Sales and Service revenue Expense: represent the company's expenditures to enable itself to operate. Common examples are electricity and water, rentals, depreciation, doubtful accounts, insurance. Equity: represent the residual equity of a business (after deducting from Assets all the liabilities) including Retained Earnings and Appropriations The options are fully listed in Retrieve General Ledger Accounts Template. |
| usage |
| Determines how the account shall be used "Header" accounts specify the title of a group of accounts. They are used only for grouping together detail accounts that have a similar purpose; that is, detail accounts are assigned to specific header accounts "Detail" accounts may have transactions logged against them The options are fully listed in Retrieve General Ledger Accounts Template. |
| manualEntriesAllowed |
| Specifies if manual entries can be made against this account using the Create Journal Entries API |
| description |
| Human understandable description for the Ledger Account |
| parentId |
| To assign a parent for this GLAccount |
| tagId |
| Used for tagging the Account Heads, based on GLAccount types. |
List General Ledger Accounts
Arguments
- type
- Integer optional
- manualEntriesAllowed
- boolean optional
- usage
- Integer optional
- disabled
- boolean optional
- parentId
- Long optional
- tagId
- Long optional
Example Requests:
glaccounts
glaccounts?type=1&manualEntriesAllowed=true&usage=1&disabled=false
glaccounts?fetchRunningBalance=true
GET https://DomainName/api/v1/glaccounts
[
{
"id": 16,
"name": "Cash",
"parentId": 1,
"glCode": "100001",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"description": "Desc",
"nameDecorated": "....Cash",
"tagId": {
"id": 10,
"name": "asset tag"
},
"organizationRunningBalance": 118437,
},
{
"id": 15,
"name": "Fund Source For Loan",
"glCode": "100002",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"description": "Desc",
"organizationRunningBalance": 118437,
}
]
Retrieve GL Accounts 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:
glaccounts/template
glaccounts/template?type=1
type is optional and integer value from 1 to 5.
1.Assets
2.Liabilities
3.Equity
4.Income
5.Expenses
GET https://DomainName/api/v1/glaccounts/template
GET https://DomainName/api/v1/glaccounts/template?type=1
{
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"accountTypeOptions": [
{
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
{
"id": 2,
"code": "accountType.liability",
"value": "LIABILITY"
},
{
"id": 3,
"code": "accountType.equity",
"value": "EQUITY"
},
{
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
{
"id": 5,
"code": "accountType.expense",
"value": "EXPENSE"
}
],
"usageOptions": [
{
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
{
"id": 2,
"code": "accountUsage.header",
"value": "HEADER"
}
],
"assetHeaderAccountOptions": [
{
"id": 1,
"name": "Two wheeler loan",
"glCode": "10001",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 2,
"code": "accountUsage.header",
"value": "HEADER"
},
"nameDecorated": "Two wheeler loan",
"tagId": {
"id": 10,
"name": "asset tag"
}
},
{
"id": 2,
"name": "VEHICLE LOAN",
"parentId": 1,
"glCode": "10002",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"usage": {
"id": 2,
"code": "accountUsage.header",
"value": "HEADER"
},
"nameDecorated": "....VEHICLE LOAN",
"tagId": {
"id": 10,
"name": "asset tag"
}
}
],
"liabilityHeaderAccountOptions": [
{
"id": 15,
"name": "liabilitieschild",
"glCode": "ltchild",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 2,
"code": "accountType.liability",
"value": "LIABILITY"
},
"usage": {
"id": 2,
"code": "accountUsage.header",
"value": "HEADER"
},
"nameDecorated": "liabilitieschild",
"tagId": {
"id": 11,
"name": "liability tag"
}
}
],
"equityHeaderAccountOptions": [
{
"id": 13,
"name": "testajax",
"glCode": "12345678",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 3,
"code": "accountType.equity",
"value": "EQUITY"
},
"usage": {
"id": 2,
"code": "accountUsage.header",
"value": "HEADER"
},
"nameDecorated": "testajax",
"tagId": {
"id": 12,
"name": "Equity tag"
}
}
],
"expenseHeaderAccountOptions": [
{
"id": 8,
"name": "Salary",
"glCode": "450098",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 5,
"code": "accountType.expense",
"value": "EXPENSE"
},
"usage": {
"id": 2,
"code": "accountUsage.header",
"value": "HEADER"
},
"nameDecorated": "Salary",
"tagId": {
"id": 14,
"name": "Expenses Tag"
}
}
],
"allowedAssetsTagOptions": [
{
"id": 10,
"name": "asset tag",
"position": 0
}
],
"allowedLiabilitiesTagOptions": [
{
"id": 11,
"name": "liability tag",
"position": 0
}
],
"allowedEquityTagOptions": [
{
"id": 12,
"name": "Equity tag",
"position": 0
}
],
"allowedIncomeTagOptions": [
{
"id": 13,
"name": "Income Tag",
"position": 0
}
],
"allowedExpensesTagOptions": [
{
"id": 14,
"name": "Expenses Tag",
"position": 0
}
]
}
Retrieve a General Ledger Account
Example Requests:
glaccounts/1
glaccounts/1?template=true
glaccounts/1?fields=name,glCode
glaccounts/1?fetchRunningBalance=true
GET https://DomainName/api/v1/glaccounts/{glaccountsId}
{
"id": 1,
"name": "Cash",
"glCode": "100001",
"disabled": false,
"manualEntriesAllowed": true,
"type": {
"id": 1,
"code": "accountType.asset1",
"value": "ASSET"
},
"usage": {
"id": 1,
"code": "accountUsage.detail",
"value": "DETAIL"
},
"description": "Desc",
"organizationRunningBalance": 118437,
}
Create a General Ledger Account
Note: You may optionally
create Hierarchical Chart of Accounts by using the "parentId"
property of an Account
Mandatory Fields |
| name, glCode, type, usage and manualEntriesAllowed |
POST https://DomainName/api/v1/glaccounts
POST glaccounts
Content-Type: application/json
Request Body:
{
"name": "Cash at Bangalore",
"glCode": "100017",
"manualEntriesAllowed": true,
"type": 1,
"tagId": "10",
"parentId": "18",
"usage": 1,
"description": "Cash at Bangalore Branch"
}
{
"resourceId": 22
}
Update a General Ledger Account
PUT https://DomainName/api/v1/glaccounts/{glaccountId}
PUT glaccounts/22
Content-Type: application/json
Request Body:
{
"name": "Cash at Bangalore rural"
}
{
"resourceId": 22,
"changes": {
"name": "Cash at Bangalore rural"
}
}
PUT glaccounts/1
Content-Type: application/json
Request Body:
{
"disabled": true
}
{
"resourceId": 1,
"changes": {
"disabled": true
}
}
Delete a General Ledger Account
Note: Only Ledger Accounts against which no transactions have been logged (either manually or by the loan or Savings portfolio) can be deleted.
DELETE https://DomainName/api/v1/glaccounts/{glaccountId}
DELETE glaccounts/1
Content-Type: application/json
No Request Body:
{
"resourceId": 1,
"changes": {}
}
Accounting Closure
An accounting closure indicates that no more journal entries may be logged (or reversed) in the system, either manually or via the portfolio with an entry date prior to the defined closure date
Field Descriptions |
| closingDate |
| The date for which the accounting closure is defined |
| officeId |
| The identifer of the branch for which accounting has been closed |
| comments |
| Description associated with an Accounting closure |
List Accounting closures
Example Requests:
glclosures
GET https://DomainName/api/v1/glclosures
[
{
"id": 7,
"officeId": 1,
"officeName": "Head Office",
"closingDate": [
2013,
1,
2
],
"deleted": false,
"createdDate": [
2013,
1,
3
],
"lastUpdatedDate": [
2013,
1,
3
],
"createdByUserId": 1,
"createdByUsername": "mifos",
"lastUpdatedByUserId": 1,
"lastUpdatedByUsername": "mifos",
"comments": "closed",
},
{
"id": 6,
"officeId": 1,
"officeName": "Head Office",
"closingDate": [
2012,
12,
13
],
"deleted": false,
"createdDate": [
2012,
12,
14
],
"lastUpdatedDate": [
2012,
12,
14
],
"createdByUserId": 1,
"createdByUsername": "mifos",
"lastUpdatedByUserId": 1,
"lastUpdatedByUsername": "mifos",
"comments": "hello",
}
]
Retrieve an Accounting Closure
Example Requests:
glclosures/1
/glclosures/1?fields=officeName,closingDate
GET https://DomainName/api/v1/glclosures/{glclosureId}
{
"id": 7,
"officeId": 1,
"officeName": "Head Office",
"closingDate": [
2013,
1,
2
],
"deleted": false,
"createdDate": [
2013,
1,
3
],
"lastUpdatedDate": [
2013,
1,
3
],
"createdByUserId": 1,
"createdByUsername": "mifos",
"lastUpdatedByUserId": 1,
"lastUpdatedByUsername": "mifos",
"comments": "closed",
}
Create an Accounting Closure
Mandatory Fields |
| officeId,closingDate |
POST https://DomainName/api/v1/glclosures
POST glclosures
Content-Type: application/json
Request Body:
{
"officeId": 1,
"closingDate": "06 December 2012",
"comments": "The accountants are heading for a carribean vacation",
"locale": "en" ,
"dateFormat": "dd MMMM yyyy"
}
{
"officeId": 1,
"resourceId": 9
}
Update an Accounting closure
Once an accounting closure is created, only the comments associated with it may be edited
PUT https://DomainName/api/v1/glclosures/{glclosureId}
PUT glclosures/1
Content-Type: application/json
Request Body:
{
"comments": "All transactions verified by Johnny Cash"
}
{
"officeId": 1,
"resourceId": 1,
"changes": {
"comments": "All transactions verified by Johnny Cash"
}
}
Delete an accounting closure
Note: Only the latest accounting closure associated with a branch may be deleted.
DELETE https://DomainName/api/v1/glclosures/{glclosureId}
DELETE glclosures/1
Content-Type: application/json
No Request Body:
{
"officeId": 1,
"resourceId": 1
}
Journal Entries
A journal entry refers to the logging of
transactions against general ledger accounts. A journal
entry may consist of several line items, each of which is either a "debit" or a "credit". The total amount of the
debits must equal the total amount of the credits or the
journal entry is said to be "unbalanced"
A journal entry directly changes the account balances on
the general ledger
Field Descriptions |
| officeId |
| The identifier of the office ( cost center) at which the financial activity occured |
| currencyCode |
| A three letter ISO code of currency. |
| glAccountId |
| The identifier of the account ( Ledger Account) against which this journal entry was made |
| transactionDate |
| The target date for which this entry was recorded |
| amount |
| The Monetary amount associated with this entry |
| comments |
| A description associated with this entry |
| entryType |
| Either a Credit(1) or a Debit(2) |
| transactionId |
| A unique Identifier for a set
of related Credit and Debit entries that make up
a "balanced" jounral Entry. For a manual entry,
this feild is a unique string. For a system generated entry, the combination of transactionId and entityId is unique |
| manualEntry |
| Flag determines if an entry is generated by the portfolio (posted automatically by the system during the lifecycle of loan or saving products) or manually created by using the Create (Balanced) Journal Entries API |
| reversed |
| Flag determines if this manual
journal entry has been reversed using the Reverse a Journal Entry
API. Note: A journal entry is reversed by logging debits for all credits that make up the Journal entry and vice-versa |
| referenceNumber |
| An additional field that is used to store additional information about the entry (Ex: chequeNo) |
| accountingRule |
| Denotes the accounting rule id for posting journal entries. |
| officeRunningBalance |
| Describes office balance after the journal entry for the Ledger Account. |
| organizationRunningBalance |
| Describes complete organization balances after the journal entry for the Ledger Account. |
| runningBalanceComputed |
| Describes whether account balances computed for the journal entry. |
| transactionDetails |
| Additional details of transaction like payment details and notes . |
List Journal Entries
The list capability of journal entries can support pagination and sorting.
Optional Arguments
- offset
- Integer optional, defaults to 0
- Indicates from what result to start from.
- limit
- Integer optional, defaults to 200
- Restricts the size of results returned. To override the default and return all entries you must explicitly pass a non-positive integer value for limit e.g. limit=0, or limit=-1
- orderBy
- String optional, one of displayName, accountNo, officeId, officeName
- Orders the results by the field indicated.
- sortBy
- String optional, one of ASC, DESC
- Indicates what way to order results if orderBy is used.
- officeId
- Integer optional
- Provides ability to restrict list of centers returned based on the office there associated with.
- glAccountId
- Integer optional
- manualEntriesOnly
- Boolean optional
- Flag determines if only manually created journal entries
are to be returned( journal entries created by
the system during lifecycle of loan or saving
products etc shall be excluded)
Set to "false" by default if not passed in explicity - fromDate
- Dateoptional
- Filters for Journal entries whose entry Date is greater than or equal to the passed in Date
- toDate
- Date optional
- Filters for Journal entries whose entry Date is lesser than or equal to the passed in Date
- transactionId
- String optional
- transactionDetails
- Boolean optional
- Flag determines if additional transactional details to be returned(like payment details and notes).
- runningBalance
- Boolean optional
- Flag determines whether running balances to be returned
Example Requests:
journalentries
journalentries?transactionId=PB37X8Y21EQUY4S
journalentries?officeId=1&manualEntriesOnly=true&fromDate=1 July 2013&toDate=15 July 2013&dateFormat=dd MMMM yyyy&locale=en
journalentries?fields=officeName,glAccountName,transactionDate
journalentries?offset=10&limit=50
journalentries?orderBy=transactionId,sortOrder=DESC
journalentries?runningBalance=true
journalentries?transactionDetails=true
GET https://DomainName/api/v1/journalentries?transactionId=PB37X8Y21EQUY4S
{
"totalFilteredRecords": 24,
"pageItems": [
{
"id": 1,
"officeId": 1,
"officeName": "Head Office",
"glAccountName": "ACCOUNT_NAME_WTYRB",
"glAccountId": 98,
"glAccountCode": "ASSET_C01367768735188",
"glAccountType": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"transactionDate": [
2011,
3,
4
],
"entryType": {
"id": 2,
"code": "journalEntrytType.debit",
"value": "DEBIT"
},
"amount": 10000,
"transactionId": "33",
"manualEntry": false,
"entityType": {
"id": 1,
"code": "productType.loan",
"value": "LOAN"
},
"entityId": 7,
"createdByUserId": 1,
"createdDate": [
2013,
5,
5
],
"createdByUserName": "mifos",
"reversed": false,
},
{
"id": 2,
"officeId": 1,
"officeName": "Head Office",
"glAccountName": "ACCOUNT_NAME_WTYRB",
"glAccountId": 98,
"glAccountCode": "ASSET_C01367768735188",
"glAccountType": {
"id": 1,
"code": "accountType.asset",
"value": "ASSET"
},
"transactionDate": [
2011,
3,
4
],
"entryType": {
"id": 1,
"code": "journalEntryType.credit",
"value": "CREDIT"
},
"amount": 10000,
"transactionId": "33",
"manualEntry": false,
"entityType": {
"id": 1,
"code": "productType.loan",
"value": "LOAN"
},
"entityId": 7,
"createdByUserId": 1,
"createdDate": [
2013,
5,
5
],
"createdByUserName": "mifos",
"reversed": false,
}
]
}
Create "Balanced" Journal Entries
Note: A Balanced (simple) Journal entry would
have atleast one "Debit" and one "Credit" entry whose
amounts are equal
Compound Journal entries may have "n" debits and "m"
credits where both "m" and "n" are greater than 0
and the net sum or all debits and credits are equal
Mandatory Fields |
| officeId, transactionDate |
| credits |
| Details of the credits contained
in the journal entry. Each credit entry contains
the following items glAccountId: Identifier of the general ledger account against which the credit entry shall be made amount: Amount of money credited comments: Optional description associated with a credit entry . |
| debits |
| Details of the debits contained
in the journal entry. Each debit entry contains the
following items glAccountId: Identifier of the general ledger account against which the debit entry shall be made amount: Amount of money debited comments: Optional description associated with a debit entry . |
POST https://DomainName/api/v1/journalentries
POST journalentries
Content-Type: application/json
Request Body:
{
"officeId": 1,
"transactionDate": "06 December 2012",
"comments": "Gifts for staff",
"locale": "en" ,
"currencyCode": "USD",
"dateFormat": "dd MMMM yyyy",
"credits":[{"glAccountId":1,
"amount":5000},
{"glAccountId":2,
"amount":5000}
],
"debits":[{"glAccountId":3,
"amount":5000},
{"glAccountId":4,
"amount":5000}
]
}
{
"officeId": 1,
"transactionId": "DNEEMS2LPD0NJ9O"
}
POST https://DomainName/api/v1/journalentries
POST journalentries
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"officeId": "1",
"transactionDate": "23 May 2013",
"referenceNumber": "547",
"currencyCode": "USD",
"comments": "asdf",
"accountingRule": "2",
"amount": "547"
}
{
"officeId":1,
"transactionId":"RS9MCISID4WK1ZM"
}
POST https://DomainName/api/v1/journalentries
POST journalentries
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"officeId": "1",
"transactionDate": "23 May 2013",
"referenceNumber": "547",
"comments": "asdf",
"accountingRule": "2",
"credits":[{"glAccountId":1,
"amount":5000},
{"glAccountId":2,
"amount":5000}
],
"debits":[{"glAccountId":3,
"amount":5000},
{"glAccountId":4,
"amount":5000}
]
}
{
"officeId":1,
"transactionId":"RS9MCISID4WK1ZM"
}
POST https://DomainName/api/v1/journalentries
POST journalentries
Content-Type: application/json
Request Body:
{
"locale": "en",
"dateFormat": "dd MMMM yyyy",
"officeId": "1",
"transactionDate": "23 May 2013",
"referenceNumber": "547",
"comments": "asdf",
"accountingRule": "3",
"credits":[{"glAccountId":1,
"amount":5000},
{"glAccountId":2,
"amount":5000}
],
"amount": "10000"
}
{
"officeId":1,
"transactionId":"RS9MCISID4WK1ZM"
}
Update Running balances for Journal Entries
This API calculates the running balances for office. If office ID not provided this API calculates running balances for all offices.
Mandatory Fields |
| officeId |
POST https://DomainName/api/v1/journalentries?command=updateRunningBalance
POST journalentries
Content-Type: application/json
Request Body:
{
"officeId": 1,
}
{
"officeId": 1,
}
Retrieve a single Entry
Example Requests:
journalentries/1
journalentries/1?fields=officeName,glAccountId,entryType,amount
journalentries/1?runningBalance=true
journalentries/1?transactionDetails=true
GET https://DomainName/api/v1/journalentries/{entryId}
{
"id": 1,
"officeId": 2,
"officeName": "sub branch 1",
"glAccountName": "Income from interest",
"glAccountId": 14,
"glAccountCode": "400001",
"glAccountType": {
"id": 4,
"code": "accountType.income",
"value": "INCOME"
},
"transactionDate": [
2012,
11,
2
],
"entryType": {
"id": 1,
"code": "journalEntryType.credit",
"value": "CREDIT"
},
"amount": 900,
"transactionId": "13",
"manualEntry": true,
"createdByUserId": 1,
"createdDate": [
2012,
11,
2
],
"createdByUserName": "mifos",
"reversed": false,
}
Reverse a Journal Entry
Note: A journal entry is reversed by logging debits for all credits that constitute the Journal entry and vice-versa. The transactionId of the "reversal Entry" is returned as the methods response
Arguments
- command
- String Mandatory, case-insensitive
- 'reverse' : Reverse the Journal Entry
GET https://DomainName/api/v1/journalentries/{transactionId}
POST journalentries/C1MAE935K0IAEYA?command=reverse
Content-Type: application/json
{
"transactionId": "YFDYMPBVVI9TRJP"
}
Search
Search API allows to search scoped resources clients, loans and groups on specified fields.
Scoped Resources |
Scoped fields |
| Client | Display Name |
| Account Number | |
| External Id | |
| Loan | Account Number |
| Client Identifiers | Document Key |
| Group | Name |
| External Id |
Search Resources
Example Requests:
search?query=000000001
search?query=Petra&resource=clients,groups
Parameters |
Description |
|
query
(mandatory) |
String which is searched on scoped resources |
|
resource
(non-mandatory) |
Scoped resources on which search can be performed. If there is no resource parameter passed then search will be performed on all scoped resources. |
Order of Search results |
List exact match results in following order
|
List partial match results in following order
|
GET https://DomainName/api/v1/search?query=000000111
[
{
"entityId": 111,
"entityAccountNo": "000000111",
"entityName": "12-A Flat Loan",
"entityType": "LOAN",
"parentId": 65,
"parentName": "aaaa aaaaa"
}
]
Templates
Templates are used for end-user features such as custom user defined document generation (AKA UGD). They are based on {{ moustache }} templates. Think of them as a sort of built-in "mail merge" functionality.
User Generated Documents (and other types of templates) can aggregate data from several Mifos X back-end API calls via mappers. Mappers can even access non-Mifos X REST services from other servers. UGDs can render such data in tables, show images, etc. TBD: Please have a look at some of the Example UGDs included in Mifos X (or the Wiki page, for now.).
Templates can be assigned to an entity like client or loan and be of a typ like document. The entity and type of a template is only there for the convenience of user agents (UIs), in order to know where to show templates for the user (i.e. which tab). The Template Engine back-end runner does not actually need this metadata.
Field Descriptions |
| name |
| Describes the document which will be created. It must be unique and appears listed in a tab at the assigned entity. |
| type |
| For now only the type document is supported. In a next version templates may be created for e-mails oder SMS. |
| entity |
| Indicates the primary resource reference. Templates may be filtered by entity and type so the relevant templates may be listed at the belonging position. |
| text |
| The actual template which may be any html-text containing mustache tags. |
| mappers |
| By default one mapper is assigned to the template depending on the entity. Mappers are used to create requests and get tags wich may be used in the template. Also mappery are in order and may depend on the previous mappers. For now mappers expect a response in JSON or plain/text. JSON contains the keys and the values. If the response is plain/text it can be accessed by {{$mapperskey.src}} |
Retrieve Template Details Template
This is a convenience resource. It can be useful when building maintenance user interface screens for templates. The template data returned consists of any or all of:
Arguments
- name
- String
- entity
- String
- type
- String
- text
- String optional
- mappers
- Mapper optional
Example Request:
templates/template
GET https://DomainName/api/v1/templates/template
{
"id": 1,
"name": "Test",
"entity": "loan",
"type": "Document",
"text": "This is a loan for {{loan.clientName}}",
"mappers": [
{
"mapperorder": 0,
"mapperkey": "loan",
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
"id": 1
}
]
}
Add a Template
Adds a new template.
Mandatory Fields |
| name |
Example Requests:
templates/1
POST https://DomainName/api/v1/templates
POST templates
Content-Type: application/json
Request Body:
{
"id": 1,
"name": "Test",
"entity": "loan",
"type": "Document",
"text": "This is a loan for {{loan.clientName}}",
"mappers": [
{
"mapperorder": 0,
"mapperkey": "loan",
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
"id": 1
}
]
}
{
"resourceId": 1
}
Retrieve all Templates
Example Requests:
templates
It is also possible to get specific templates by entity and type:
templates?type=0&entity=0
Entity |
Id | Type |
Id |
| client | 0 | Document | 0 |
| loan | 1 | E-Mail (not yet) | 1 |
| SMS (not yet) | 2 |
GET https://DomainName/api/v1/templates
[
{
"id": 1,
"name": "Test",
"entity": "loan",
"type": "Document",
"text": "This is a loan for {{loan.clientName}}",
"mappers": [
{
"mapperorder": 0,
"mapperkey": "loan",
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
"id": 1
}
]
}
]
Retrieve a Template
Example Requests:
templates/1
GET https://DomainName/api/v1/templates/{Id}
{
"id": 1,
"name": "Test",
"entity": "loan",
"type": "Document",
"text": "This is a loan for {{loan.clientName}}",
"mappers": [
{
"mapperorder": 0,
"mapperkey": "loan",
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
"id": 1
}
]
}
Update a Template
PUT https://DomainName/api/v1/templates/{templateId}
PUT templates/1
Content-Type: application/json
Request Body:
{
"id": 1,
"name": "Test",
"entity": "loan",
"type": "Document",
"text": "This is a loan for {{loan.clientName}}",
"mappers": [
{
"mapperorder": 0,
"mapperkey": "loan",
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
"id": 1
}
]
}
{
"resourceId": 1
}
Delete a Template
DELETE https://DomainName/api/v1/templates/{templateId}
DELETE templates/1
Content-Type: application/json
No Request Body:
{
"resourceId": 1
}