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/keithwoodlock/mifosx/wiki/HTTP-API-Error-codes",
"httpStatusCode": "400", 
"defaultUserMessage": "Validation errors exist.", 
"userMessageGlobalisationCode": "validation.msg.validation.errors.exist", 
"errors": [ 
	{
	"developerMessage": "The parameter name cannot be blank.",
	"defaultUserMessage": "The parameter name cannot be blank.",
	"userMessageGlobalisationCode": "validation.msg.office.name.cannot.be.blank", 
	"parameterName": "name", 
	"value": null, 
	"args": [] 
	}, 
	{ 
	"developerMessage": "The parameter openingDate cannot be blank.", 
	"defaultUserMessage": "The parameter openingDate cannot be blank.",
	"userMessageGlobalisationCode": "validation.msg.office.openingDate.cannot.be.blank",
	"parameterName": "openingDate", "value": null, "args": [] 
	}, 
	{
	"developerMessage": "The parameter parentId cannot be blank.",
	"defaultUserMessage": "The parameter parentId cannot be blank.",
	"userMessageGlobalisationCode":
	"validation.msg.office.parentId.cannot.be.blank", "parameterName":
	"parentId", "value": null, "args": []
	} 
] 
}

Clients

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

Field Descriptions

accountNo

If provided during client creation, its value is set as account no. for client account, otherwise an auto generated account no. is put in place based on the configured strategy.

firstname

Facility to break up name into parts suitable for humans.

middlename

Facility to break up name into parts suitable for humans.

lastname

Facility to break up name into parts suitable for humans.

fullname

Facility to set name of a client or business that doesnt suit the firstname,middlename,lastname structure.

externalId

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

List Clients

Example Requests:

clients

clients?fields=displayName,officeName,joinedDate


GET https://DomainName/api/v1/clients


[
    {
        "id": 2,
        "accountNo": "000000002",
        "externalId": "one/78",
        "fullname": "New Business to Create",
        "displayName": "New Business to Create",
        "officeId": 1,
        "officeName": "Head Office",
        "joinedDate": [2006,6,13]
    },
    {
        "id": 1,
        "accountNo": "000000001",
        "externalId": "786YYH7",
        "firstname": "Petra",
        "lastname": "Yton",
        "displayName": "Petra Yton",
        "officeId": 1,
        "officeName": "Head Office",
        "joinedDate": [2009,3,4]
    }
]

Retrieve Client Details Template

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

Field Defaults
Allowed Value Lists

Example Request:

clients/template


GET https://DomainName/api/v1/clients/template


{
    "officeId": 1,
    "joinedDate": [
        2013,
        2,
        5
    ],
    "allowedOffices": [
        {
            "id": 1,
            "name": "Head Office",
            "nameDecorated": "Head Office"
        }
    ]
}

Retrieve a Client

Example Requests:

clients/1

clients/1?template=true

clients/1?fields=id,displayName,officeName


GET https://DomainName/api/v1/clients/{clientId}


{
    "id": 1,
    "accountNo": "000000001",
    "externalId": "786YYH7",
    "firstname": "Petra",
    "lastname": "Yton",
    "displayName": "Petra Yton",
    "officeId": 1,
    "officeName": "Head Office",
    "joinedDate": [
        2009,
        3,
        4
    ]
}

Create a Client

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

Mandatory Fields

firstname and lastname OR fullname
, joinedDate, officeId


POST https://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",
    "joinedDate": "04 March 2009"
}


{
    "officeId": 1,
    "clientId": 1,
    "resourceId": 1
}


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


{
    "officeId": 1,
    "clientId": 2,
    "resourceId": 2
}

Update a Client


PUT https://DomainName/api/v1/clients/{clientId}


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


{
    "officeId": 1,
    "clientId": 1,
    "resourceId": 1,
    "changes": {
        "externalId": "786444UUUYYH7",
        "joinedDate": "09 June 2006",
        "dateFormat": "dd MMMM yyyy",
        "locale": "en"
    }
}

Retrieve a Client's Loan Account Summary

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

Example Requests:

clients/1/loans

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


GET https://DomainName/api/v1/clients/{clientId}/loans


{
    "anyLoanCount": 9,
    "pendingApprovalLoanCount": 4,
    "pendingApprovalLoans": [
        {
            "id": 48,
            "accountNo": "48",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 100,
                "code": "loanStatusType.submitted.and.pending.approval",
                "value": "Submitted and pending approval"
            }
        },
        {
            "id": 50,
            "accountNo": "50",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 100,
                "code": "loanStatusType.submitted.and.pending.approval",
                "value": "Submitted and pending approval"
            }
        },
        {
            "id": 51,
            "accountNo": "51",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 100,
                "code": "loanStatusType.submitted.and.pending.approval",
                "value": "Submitted and pending approval"
            }
        },
        {
            "id": 62,
            "accountNo": "62",
            "productId": 3,
            "productName": "Further Loan Product",
            "status": {
                "id": 100,
                "code": "loanStatusType.submitted.and.pending.approval",
                "value": "Submitted and pending approval"
            }
        }
    ],
    "activeLoanCount": 2,
    "openLoans": [
        {
            "id": 46,
            "accountNo": "46",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 300,
                "code": "loanStatusType.active",
                "value": "Active"
            }
        },
        {
            "id": 60,
            "accountNo": "60",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 300,
                "code": "loanStatusType.active",
                "value": "Active"
            }
        }
    ],
    "closedLoanCount": 3,
    "closedLoans": [
        {
            "id": 22,
            "accountNo": "22",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 700,
                "code": "loanStatusType.overpaid",
                "value": "Overpaid"
            }
        },
        {
            "id": 33,
            "accountNo": "33",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 601,
                "code": "loanStatusType.closed.written.off",
                "value": "Closed (written off)"
            }
        },
        {
            "id": 44,
            "accountNo": "44",
            "productId": 1,
            "productName": "PORetailLoan",
            "status": {
                "id": 600,
                "code": "loanStatusType.closed.obligations.met",
                "value": "Closed (obligations met)"
            }
        }
    ]
}

Retrieve a Client's Notes

Note: Notes are returned in descending createOn order.

Example Requests:

clients/2/notes

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


GET https://DomainName/api/v1/clients/{clientId}/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
    }
]

Add a Client Note


POST https://DomainName/api/v1/clients/{clientId}/notes


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


{
    "officeId": 1,
    "clientId": 1,
    "resourceId": 76
}

Retrieve a Client Note

Example Requests:

clients/1/notes/76

clients/1/notes/76?fields=note,createdOn,createdByUsername


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


{
    "id": 76,
    "clientId": 1,
    "noteType": {
        "id": 100,
        "code": "noteType.client",
        "value": "Client note"
    },
    "note": "a note about the client",
    "createdById": 1,
    "createdByUsername": "mifos",
    "createdOn": 1359463135000,
    "updatedById": 1,
    "updatedByUsername": "mifos",
    "updatedOn": 1359463135000
}

Update a Client Note


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


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


{
    "officeId": 1,
    "clientId": 1,
    "resourceId": 76,
    "changes": {
        "note": "and here the note is updated nicely."
    }
}

Groups

Groups are collection of clients for specific purpose (JLG,SHG, Program etc)

Field Descriptions

office_id

It stores the officeid of office, to this officer Group belongs.

loan_officer_id

Id of the officer who manages this group.

name

Human friendly identity of the Group (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.

is_deleted

Indicator for active or archived groups.

Create a Group

Mandatory Fields

name
officeId
clients


						POST https://DomainName/mifosng-provider/api/v1/groups


						POST groups
						Content-Type: application/json Request Body:
						{
						"officeId":"1",
						"name":"TA Group",
						"externalId":"",
						"clientMembers":["82","83","84"]
						}


						{"resourceId":24,"changes":{}}

List Groups

Example Requests:

groups


GET https://DomainName/mifosng-provider/api/v1/groups


[{
    "id": 1,
    "name": "GWT_2",
    "externalId": "GWT_EX_ID_2",
    "officeId": 7,
    "officeName": "Z2"
}, {
    "id": 2,
    "name": "group22",
    "externalId": "11234",
    "officeId": 1,
    "officeName": "Head Office"
}, {
    "id": 3,
    "name": "PlusOne",
    "officeId": 22,
    "officeName": "North Point Office"
}]

Retrieve a Group

Example Requests:

groups/10


GET https://DomainName/mifosng-provider/api/v1/groups/10


{
    "id": 10,
    "name": "test123",
    "externalId": "tejjjst",
    "officeId": 1,
    "officeName": "Head Office",
    "clientMembers": [{
        "id": 1,
        "displayName": "Willie O\u0027Meara"
    }]
}

Retrieve a Groups's Loan Account Summary

An example of how a loan portfolio summary can be provided. This one contains quite a bit of redundant data (like the counts)

Example Requests:

groups/7/loans


GET https://DomainName/mifosng-provider/api/v1/groups/7/loans


{
    "anyLoanCount": 1,
    "pendingApprovalLoanCount": 0,
    "pendingApprovalLoans": [],
    "awaitingDisbursalLoanCount": 0,
    "awaitingDisbursalLoans": [],
    "activeLoanCount": 1,
    "openLoans": [{
        "id": 79,
        "productId": 1,
        "productName": "1-PORetailLoan",
        "accountStatusId": 300
    }],
    "closedLoanCount": 0,
    "closedLoans": [],
    "anyIndividualLoanCount": 3,
    "pendingApprovalIndividualLoanCount": 0,
    "pendingApprovalIndividualLoans": [],
    "awaitingDisbursalIndividualLoanCount": 0,
    "awaitingDisbursalIndividualLoans": [],
    "activeIndividualLoanCount": 3,
    "openIndividualLoans": [{
        "id": 80,
        "productId": 17,
        "productName": "17-Intrasoft Business Loan",
        "accountStatusId": 300
    }, {
        "id": 81,
        "productId": 1,
        "productName": "1-PORetailLoan",
        "accountStatusId": 300
    }, {
        "id": 82,
        "productId": 13,
        "productName": "13-A Flat Loan",
        "accountStatusId": 300
    }],
    "closedIndividualLoanCount": 0,
    "closedIndividualLoans": []
}

Update a Group


PUT https://DomainName/mifosng-provider/api/v1/groups/{groupid}


PUT groups/7 
Content-Type: application/json 
Request Body:
{
    "officeId": "26",
    "name": "Laxmi SSG U",
    "externalId": "Unq 2--124",
    "clientMembers": ["91", "93", "94"]
}


{
	"resourceId":7,
	"changes":{}
}

Assign a Loan Officer to Group


POST https://DomainName/mifosng-provider/api/v1/groups/{groupid}/command/assign_loanofficer


POST groups/20/command/assign_loanofficer 
Content-Type: application/json 
Request Body:
{
{"loanOfficerId":"1"}
}


{
	"resourceId":20,
	"changes":{}
}

Unassign a loan officer to a Group


POST https://DomainName/mifosng-provider/api/v1/groups/{groupid}/command/assign_loanofficer


POST groups/20/command/unassign_loanofficer 
Content-Type: application/json 
Request Body:
{
{"loanOfficerId":"1"}
}


{
	"resourceId":20,
	"changes":{}
}

Delete a Group


POST https://DomainName/mifosng-provider/api/v1/groups/{groupid}


DELETE groups/7


{
	"resourceId":7,
	"changes":{}
}

Loans

Field Descriptions

principal

The amount to be provided in the loan.

externalId

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

inArrearsTolerance

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

numberOfRepayments

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

interestRatePerPeriod

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

repaymentEvery

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

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

repaymentFrequencyType

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

interestRateFrequencyType

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

amortizationType

Example Values: Equal principle payments, Equal installments

interestType

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

interestCalculationPeriodType

Example Values: Same as repayment period, Daily

Retrieve Loan Details Template

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

Field Defaults
Allowed Value Lists

Arguments

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

Example Requests:

loans/template?clientId=1&productId=1

loans/template?clientId=1


GET https://DomainName/api/v1/loans/template?clientId=1


{
    "clientId": 1,
    "clientName": "Petra Yton",
    "expectedDisbursementDate": [
        2013,
        2,
        5
    ],
    "loanOfficerOptions": [
        {
            "id": 1,
            "firstname": "John",
            "lastname": "Doe",
            "displayName": "Doe, John",
            "officeId": 1,
            "officeName": "Head Office",
            "isLoanOfficer": true
        }
    ],
    "productOptions": [
        {
            "id": 1,
            "name": "A new loan product for me"
        }
    ],
    "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"
        }
    ],
    "repaymentStrategyOptions": [
        {
            "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)"
        }
    ],
    "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"
        }
    ],
    "fundOptions": [
        {
            "id": 1,
            "name": "EU Agri Fund"
        }
    ],
    "chargeOptions": [
        {
            "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"
            }
        }
    ],
    "chargeTemplate": {
        "active": false,
        "penalty": false,
        "chargeCalculationTypeOptions": [
            {
                "id": 1,
                "code": "chargeCalculationType.flat",
                "value": "Flat"
            },
            {
                "id": 2,
                "code": "chargeCalculationType.percent.of.amount",
                "value": "% Amount"
            }
        ],
        "chargeTimeTypeOptions": [
            {
                "id": 1,
                "code": "chargeTimeType.disbursement",
                "value": "Disbursement"
            },
            {
                "id": 2,
                "code": "chargeTimeType.specifiedDueDate",
                "value": "Specified due date"
            }
        ]
    }
}

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": 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
  },
  "clientId": 1,
  "clientName": "Petra Yton",
  "clientOfficeId": 1,
  "loanProductId": 1,
  "loanProductName": "A new loan product for me",
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "decimalPlaces": 2,
    "displaySymbol": "$",
    "nameCode": "currency.USD",
    "displayLabel": "US Dollar ($)"
  },
  "principal": 100000,
  "termFrequency": 12,
  "termPeriodFrequencyType": {
    "id": 2,
    "code": "termFrequency.periodFrequencyType.months",
    "value": "Months"
  },
  "numberOfRepayments": 12,
  "repaymentEvery": 1,
  "repaymentFrequencyType": {
    "id": 2,
    "code": "repaymentFrequency.periodFrequencyType.months",
    "value": "Months"
  },
  "transactionProcessingStrategyId": 1,
  "amortizationType": {
    "id": 1,
    "code": "amortizationType.equal.installments",
    "value": "Equal installments"
  },
  "interestRatePerPeriod": 2,
  "interestRateFrequencyType": {
    "id": 2,
    "code": "interestRateFrequency.periodFrequencyType.months",
    "value": "Per month"
  },
  "annualInterestRate": 24,
  "interestType": {
    "id": 0,
    "code": "interestType.declining.balance",
    "value": "Declining Balance"
  },
  "interestCalculationPeriodType": {
    "id": 1,
    "code": "interestCalculationPeriodType.same.as.repayment.period",
    "value": "Same as repayment period"
  },
  "timeline": {
    "submittedOnDate": [
      2011,
      9,
      20
    ],
    "submittedByUsername": "mifos",
    "submittedByFirstname": "App",
    "submittedByLastname": "Administrator",
    "expectedDisbursementDate": [
      2011,
      9,
      20
    ],
    "expectedMaturityDate": [
      2012,
      9,
      20
    ]
  }
}

Calculate loan repayment schedule

Mandatory Fields

productId, principal, loanTermFrequency, loanTermFrequencyType, numberOfRepayments, repaymentEvery, repaymentFrequencyType, interestRatePerPeriod, interestRateFrequencyType, 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,
    "interestRateFrequencyType": 2,
    "amortizationType": 1,
    "interestType": 0,
    "interestCalculationPeriodType": 1,
    "expectedDisbursementDate": "20 September 2011",
    "transactionProcessingStrategyId": 2
}


{
  "loanTermInDays": 366,
  "currency": {
    "code": "UGX",
    "name": "Uganda Shilling",
    "decimalPlaces": 2,
    "displaySymbol": "USh",
    "nameCode": "currency.UGX",
    "displayLabel": "Uganda Shilling (USh)"
  },
  "cumulativePrincipalDisbursed": 100000,
  "cumulativePrincipalDue": 100000,
  "cumulativePrincipalOutstanding": 0,
  "cumulativeInterestExpected": 13471.52,
  "cumulativeFeeChargesToDate": 0,
  "totalCostOfLoan": 13471.52,
  "totalExpectedRepayment": 113471.52,
  "totalPaidToDate": 0,
  "totalWaivedToDate": 0,
  "totalWrittenOffToDate": 0,
  "totalOutstanding": 113471.52,
  "totalInArrears": 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, numberOfRepayments, repaymentEvery, repaymentFrequencyType, interestRatePerPeriod, interestRateFrequencyType, amortizationType, interestType, interestCalculationPeriodType, expectedDisbursementDate, submittedOnDate, transactionProcessingStrategyId


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": "100,000.00",
    "loanTermFrequency": 12,
    "loanTermFrequencyType": 2,
    "numberOfRepayments": 12,
    "repaymentEvery": 1,
    "repaymentFrequencyType": 2,
    "interestRatePerPeriod": 2,
    "interestRateFrequencyType": 2,
    "amortizationType": 1,
    "interestType": 0,
    "interestCalculationPeriodType": 1,
    "expectedDisbursementDate": "20 September 2011",
    "submittedOnDate": "20 September 2011",
    "transactionProcessingStrategyId": 1
}


{
    "officeId": 1,
    "clientId": 1,
    "loanId": 1,
    "resourceId": 1
}

Approve 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=approve
Content-Type: application/json


{
  "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:
{
    "locale": "en",
    "dateFormat": "dd MMMM yyyy",
    "actualDisbursementDate": "20 September 2011",
    "note": "Any additional info related to disbursement of funds to applicant."
}


{
  "officeId": 1,
  "clientId": 1,
  "loanId": 4,
  "resourceId": 4,
  "changes": {
    "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": "20 September 2011"
  }
}

Undo Loan Disbursal


POST https://DomainName/api/v1/loans/{loanId}?command=undoDisbursal


POST loans/1?command=undoDisbursal
Content-Type: application/json


{
  "officeId": 1,
  "clientId": 1,
  "loanId": 4,
  "resourceId": 4,
  "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,
        "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:
{
	"locale": "en_GB",
	"dateFormat": "dd MMMM yyyy",
	"transactionDate": "14 May 2012",
	"transactionAmount": "559.88",
	"note": "Optional note related to the transaction."
}


{
  "officeId": 1,
  "clientId": 1,
  "loanId": 5,
  "resourceId": 3,
  "changes": {
    "transactionDate": "14 May 2012",
    "transactionAmount": "559.88",
    "locale": "en_GB",
    "dateFormat": "dd MMMM yyyy",
    "note": "Optional note related to the transaction."
  }
}

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."
  }
}

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
}

Loan Charges

Loan charges can be fees or penalities. They can be defined using the charges api and associated with loan products.

Field Descriptions

chargeId

The id of the charge definition.

amount

The flat amount or percenatge amount of the charge. (depending on its type)

dueDate

The date the loan charge is due for collection. Relevant for charges defined as specified due date.

Retrieve Loan 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:

loans/1/charges/template


GET https://DomainName/api/v1/loans/{loanId}/charges/template


{
	{
  "amountPaid": 0,
  "amountWaived": 0,
  "amountWrittenOff": 0,
  "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"
      }
    }
  ],
  "penalty": false
}
}

Create a Loan Charge

Mandatory Fields

chargeId, amount, dueDate (depending on chargeTimeType of charge definition)


POST https://DomainName/api/v1//loans/{loanId}/charges


POST /loans/1/charges
Content-Type: application/json 
Request Body:
{
	"locale": "en",
	"dateFormat": "dd MMMM yyyy",
	"chargeId": 1,
	"amount": "333",
	"dueDate": "21 November 2011"
}


{
 	"officeId": 1,
	"clientId": 1,
	"loanId": 1,
	"resourceId": 14
}

Update a Loan Charge


PUT https://DomainName/api/v1//loans/{loanId}/charges/{loanChargeId}


PUT /loans/1/charges/14
Content-Type: application/json 
Request Body:
{
	"locale": "en",
	"amount": "650"
}


{
  "officeId": 1,
  "clientId": 1,
  "loanId": 1,
  "resourceId": 14,
  "changes": {
    "amount": 650,
    "locale": "en"
  }
}

Delete a Loan Charge


DELETE https://DomainName/api/v1//loans/{loanId}/charges/{loanChargeId}


DELETE /loans/1/charges/14
Content-Type: application/json


{
  "officeId": 1,
  "clientId": 1,
  "loanId": 1,
  "resourceId": 14
}

Retrieve a Loan Charge


GET https://DomainName/api/v1//loans/{loanId}/charges/{loanChargeId}


GET /loans/1/charges/1
Content-Type: application/json


{
  "id": 14,
  "chargeId": 1,
  "name": "Bank Fee (per installment)",
  "chargeTimeType": {
    "id": 2,
    "code": "chargeTimeType.specifiedDueDate",
    "value": "Specified due date"
  },
  "dueDate": [
    2011,
    11,
    21
  ],
  "chargeCalculationType": {
    "id": 1,
    "code": "chargeCalculationType.flat",
    "value": "Flat"
  },
  "percentage": 0,
  "amountPercentageAppliedTo": 0,
  "currency": {
    "code": "UGX",
    "name": "Uganda Shilling",
    "decimalPlaces": 2,
    "displaySymbol": "USh",
    "nameCode": "currency.UGX",
    "displayLabel": "Uganda Shilling (USh)"
  },
  "amount": 650,
  "amountPaid": 0,
  "amountWaived": 0,
  "amountWrittenOff": 0,
  "amountOutstanding": 650,
  "amountOrPercentage": 650,
  "penalty": false
}

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?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
}

Fixed Deposit Account:

Field Descriptions

deposit :

The amount to be deposited in the deposit account.

externalId :

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

tenureInMonths:

The time period for fixed deposit to mature(in months).
Eg:The period of deposit shall be 24 months
tenureInMonths=24.

renewalAllowed:

Used to renew the deposit account after maturity.
if 'true' the account is eligible for renew.

isInterestWithdrawable:

Denotes whether one can withdraw the interest from deposit account.

interestCompoundingAllowed:

Denotes whether the interest is calculated on compounding basis or not.
if true:interest calculated on compounding basis, else interest calculated on simple calculation basis.

maturityInterestRate:

Denotes the interest rate % on deposit amount.

preClosureInterestRate:

Denotes the interest rate % of deposit amount for preclosing accounts.
This rate is applicable if the account is preclosed.

interestCompoundedEvery:

Interest is calculated on deposit amount for every interestCompoundedEvery period

lockinPeriod:

Defines a lockin period for deposit account.
With in the lockin period one cannot preclose the deposit account.

Retrieve Deposit Account Details Template:

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

Field Defaults
Allowed Value Lists

Arguments

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

Example Requests:

depositaccounts/template?clientId=17&productId=1

depositaccounts/template?clientId=17

GET https://Domain Name/api/v1/depositaccounts/template?clientId={clientId}&productId={productId}


{
  "clientId": 1,
  "clientName": "First Client",
  "productId": 1,
  "productName": "MyFirstDepositProduct",
  "currency": {
    "code": "USD",
    "name": "",
    "decimalPlaces": 2,
    "displaySymbol": "",
    "nameCode": "",
    "displayLabel": " [USD]"
  },
  "deposit": 100,
  "maturityInterestRate": 6,
  "tenureInMonths": 12,
  "projectedCommencementDate": [
    2013,
    2,
    6
  ],
  "interestCompoundedEvery": 1,
  "interestCompoundedEveryPeriodType": {
    "id": 2,
    "code": "deposit.interest.compounding.period.periodFrequencyType.months",
    "value": "Months"
  },
  "renewalAllowed": true,
  "preClosureAllowed": true,
  "preClosureInterestRate": 3,
  "isInterestWithdrawable": false,
  "interestCompoundingAllowed": true,
  "interestCompoundedEveryPeriodTypeOptions": [
    {
      "id": 2,
      "code": "deposit.interest.compounding.period.periodFrequencyType.months",
      "value": "Months"
    }
  ],
  "productOptions": [
    {
      "id": 1,
      "name": "MyFirstDepositProduct"
    }
  ],
  "availableInterestForWithdrawal": 0,
  "availableWithdrawalAmount": 0,
  "todaysDate": [
    2013,
    2,
    6
  ],
  "isLockinPeriodAllowed": true,
  "lockinPeriod": 0,
  "lockinPeriodType": {
    "id": 2,
    "code": "deposit.interest.compounding.period.periodFrequencyType.months",
    "value": "Months"
  },
  "availableInterest": 0,
  "interestPostedAmount": 0
}

GET https://Domain Name/api/v1/depositaccounts/template?clientId={clientId}

{
  "clientId": 1,
  "clientName": "First Client",
  "renewalAllowed": false,
  "preClosureAllowed": false,
  "isInterestWithdrawable": false,
  "interestCompoundingAllowed": true,
  "interestCompoundedEveryPeriodTypeOptions": [
    {
      "id": 2,
      "code": "deposit.interest.compounding.period.periodFrequencyType.months",
      "value": "Months"
    }
  ],
  "productOptions": [
    {
      "id": 1,
      "name": "MyFirstDepositProduct"
    }
  ],
  "availableInterestForWithdrawal": 0,
  "availableWithdrawalAmount": 0,
  "todaysDate": [
    2013,
    2,
    6
  ],
  "isLockinPeriodAllowed": true,
  "availableInterest": 0,
  "interestPostedAmount": 0
}

Retrieve a fixeddeposit:

Arguments

associations: optional, 'all' deposit associations are itemised below; Associations are just extra pieces of data that you might or might not want to retrieve.; 'all': Gets all association data.; 'permissions': Data that describes what things can happen to the deposit in its current state. Very specific to the needs of the current Individual Lending client application.

Example Requests:

depositaccounts/1

depositaccounts/1?associations=all

GET https://DomainName/api/v1/depositaccounts/{depositaccountId}

{
{
	"id": 5,
	"status": {
		"id": 100,
		"code": "depositStatusType.submitted.and.pending.approval",
		"value": "Submitted and pending approval"
	},
	"clientId": 17,
	"clientName": "Agri",
	"productId": 1,
	"productName": "Micro Savings",
	"currency": {
		"code": "INR",
		"name": "Indian Rupee",
		"decimalPlaces": 2,
		"nameCode": "currency.INR",
		"displayLabel": "Indian Rupee [INR]"
	},
	"deposit": 200.000000,
	"maturityInterestRate": 12.000000,
	"tenureInMonths": 12,
	"projectedCommencementDate": [2012,	12,	16],
	"maturedOn": [2013,	12,	15],
	"projectedInterestAccrued": 24.000000,
	"projectedMaturityAmount": 224.000000,
	"interestCompoundedEvery": 6,
	"interestCompoundedEveryPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"renewalAllowed": true,
	"preClosureAllowed": true,
	"preClosureInterestRate": 5.000000,
	"isInterestWithdrawable": true,
	"interestPaid": 0.000000,
	"interestCompoundingAllowed": false,
	"permissions": {
		"rejectAllowed": true,
		"withdrawnByApplicantAllowed": true,
		"undoApprovalAllowed": false,
		"pendingApproval": true,
		"isInterestWithdrawalAllowed": true,
		"renewelAllowed": false,
		"isMaturedDepositAccount": false,
		"anyActionOnAccountAllowed": true
	},
	"availableInterestForWithdrawal": 0,
	"availableWithdrawalAmount": 200.000000,
	"todaysDate": [2013, 1,	30],
	"isLockinPeriodAllowed": true,
	"lockinPeriod": 0,
	"lockinPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"availableInterest": 0.000000,
	"interestPostedAmount": 0.000000,
	"imageKey": "/root/.mifosx/DefaultDemoTenant/images/clients/33/places.png"
}
}

Create a New DepositAccount / Submit a DepositAccount Application

Arguments

command: String Optional, case-insensitive; The default action is to Submit a New DepositAccount Application ("Submitted and awaiting approval" status).

Mandatory Fields

clientId, productId, deposit, maturityInterestRate, commencementDate

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

POST depositaccount
Content-Type: application/json
Request Body:
{
    "clientId": "17",
	"dateFormat": "dd MMMM yyyy",
	"locale": "en",
	"productId": "1",
	"commencementDate": "25 January 2013",
	"externalId": "123",
	"deposit": "20000",
	"tenureInMonths": "3",
	"renewalAllowed": "true",
	"preClosureAllowed": "true",
	"interestCompoundingAllowed": "false",
	"isInterestWithdrawable": "true",
	"isLockinPeriodAllowed": "true",
	"maturityInterestRate": "12",
	"preClosureInterestRate": "5",
	"interestCompoundedEvery": "6",
	"interestCompoundedEveryPeriodType": "2",
	"lockinPeriod": "1",
	"lockinPeriodType": "2"
}

{
 "resourceId": 42
}

Approval, Reject or Withdraw a DepositAccount Application

Arguments

command: String Mandatory, case-insensitive; 'approve' : Approve DepositAccount; 'reject' : Reject DepositAccount; 'withdrewbyclient' : Client Withdrew DepositAccount Application
Deposit amount: IntegerMandatory
Deposit interest rate: IntegerMandatory
Tenure month: IntegerMandatory
Interest posted every: IntegerMandatory

Mandatory Fields

eventDate

POST https://DomainName/api/v1/depositaccounts/{depositaccountId}

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


{
"resourceId": 37
}

Delete a DepositAccount

Note: depositaccount is deleted.

DELETE https://Domain Name/api/v1/depositaccounts/{depositaccountsId}

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

{
"resourceId": 1
}

Saving Account :

Field Descriptions

savingsDepositAmountPerPeriod :

The amount to be depositd in the savingaccount for every period.
If the account is regular account enter what ever the amount you want to deposit

externalId :

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

tenure :

denotes the tenure period of savings account

depositEvery :

For every 'depositEvery' period the client has to deposit 'savingsDepositAmountPerPeriod' amount

interestCalculationMethod:

denotes on what basis the interest is calculated
e.g. AverageBal,Monthly Collection etc

recurringInterestRate :

The interest rate applicable on recurring deposit savingaccounts

savingInterestRate :

The interest rate applicable on regular savingaccounts

interestPostEvery:

Denotes for how many months the interest is posted for recurring/regular saving accounts

lockinPeriod :

With in a lockin period you cannot withdraw whole money(cannot Preclose)

Retrieve SavingAccount Details Template :

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

Field Defaults
Allowed Value Lists

Arguments

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

Example Requests:

savingaccounts/template?clientId=25&productId=5

savingaccounts/template?clientId=25

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

{
	"clientId": 25,
	"clientName": "Clark Kent",
	"productId": 5,
	"productName": "Shares",
	"productType": {
		"id": 2,
		"code": "savings.product.savingProductType.regular",
		"value": "Regular"
	},
	"currencyData": {
		"code": "ZAR",
		"name": "South African Rand",
		"decimalPlaces": 2,
		"displaySymbol": "R",
		"nameCode": "currency.ZAR",
		"displayLabel": "South African Rand (R)"
	},
	"savingsDepositAmountPerPeriod": 500.000000,
	"savingsFrequencyType": {
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	},
	"recurringInterestRate": 12.000000,
	"savingInterestRate": 12.000000,
	"interestType": {
		"id": 2,
		"code": "savings.interest.type.savingsInterestType.compounding",
		"value": "Compounding"
	},
	"interestCalculationMethod": {
		"id": 1,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
		"value": "AverageBalance"
	},
	"tenure": 12,
	"tenureType": {
		"id": 1,
		"code": "savings.tenure.tenureTypeEnum.fixedPeriod",
		"value": "FixedPeriod"
	},
	"projectedCommencementDate": [2013,
	2,
	1],
	"preClosureAllowed": true,
	"isLockinPeriodAllowed": false,
	"lockinPeriod": 0,
	"lockinPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"depositEvery": 1,
	"productOptions": [{
		"id": 4,
		"name": "sb01"
	},
	{
		"id": 5,
		"name": "Shares"
	}],
	"currencyOptions": [{
		"code": "ZAR",
		"name": "South African Rand",
		"decimalPlaces": 2,
		"displaySymbol": "R",
		"nameCode": "currency.ZAR",
		"displayLabel": "South African Rand (R)"
	},
	{
		"code": "VND",
		"name": "Vietnamese Dong",
		"decimalPlaces": 2,
		"nameCode": "currency.VND",
		"displayLabel": "Vietnamese Dong [VND]"
	}],
	"savingsProductTypeOptions": [{
		"id": 1,
		"code": "savings.product.savingProductType.reccuring",
		"value": "Recurring"
	},
	{
		"id": 2,
		"code": "savings.product.savingProductType.regular",
		"value": "Regular"
	}],
	"tenureTypeOptions": [{
		"id": 1,
		"code": "savings.tenure.tenureTypeEnum.fixedPeriod",
		"value": "FixedPeriod"
	},
	{
		"id": 2,
		"code": "savings.tenure.tenureTypeEnum.perpetual",
		"value": "Perpetual"
	}],
	"savingFrequencyOptions": [{
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	}],
	"savingsInterestTypeOptions": [{
		"id": 1,
		"code": "savings.interest.type.savingsInterestType.simple",
		"value": "Simple"
	},
	{
		"id": 2,
		"code": "savings.interest.type.savingsInterestType.compounding",
		"value": "Compounding"
	}],
	"lockinPeriodTypeOptions": [{
		"id": 2,
		"code": "savings.product.lockin.period.type.months",
		"value": "Months"
	}],
	"interestCalculationOptions": [{
		"id": 1,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
		"value": "AverageBalance"
	},
	{
		"id": 3,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.monthlycllection",
		"value": "MonthlyCollection"
	}],
	"outstandingAmount": 0,
	"dueAmount": 0,
	"interestPostEvery": 3,
	"interestPostFrequency": {
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	}
}

Retrieve a SavingAccount :

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

Arguments

associations: optional, Either 'all' or a comma separated list of savings 'associations' (itemised below).; Associations are just extra pieces of data that you might or might not want to retrieve.; 'all': Gets all association data.; 'permissions': Data that describes what things can happen to the saving account in its current state. Very specific to the needs of the current Individual Lending client application.; 'savingScheduleData': Some derived data that; 'transactions' : Some data

Example Requests :

savingaccounts/15

savingaccounts/15?associations=all

GET https://DomainName/api/v1/savingaccounts/{savingaccountId}

{
	"id": 15,
	"status": {
		"id": 100,
		"code": "depositStatusType.submitted.and.pending.approval",
		"value": "Submitted and pending approval"
	},
	"externalId": "23",
	"clientId": 50,
	"clientName": "Brendan Fahy",
	"productId": 4,
	"productName": "sb01",
	"productType": {
		"id": 2,
		"code": "savings.product.savingProductType.regular",
		"value": "Regular"
	},
	"currencyData": {
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	},
	"savingsDepositAmountPerPeriod": 200.000000,
	"savingsFrequencyType": {
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	},
	"totalDepositAmount": 0.000000,
	"recurringInterestRate": 4.000000,
	"savingInterestRate": 4.000000,
	"interestType": {
		"id": 1,
		"code": "savings.interest.type.savingsInterestType.simple",
		"value": "Simple"
	},
	"interestCalculationMethod": {
		"id": 1,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
		"value": "AverageBalance"
	},
	"tenure": 12,
	"tenureType": {
		"id": 1,
		"code": "savings.tenure.tenureTypeEnum.fixedPeriod",
		"value": "FixedPeriod"
	},
	"projectedCommencementDate": [2013,
	2,
	1],
	"projectedInterestAccuredOnMaturity": 0.000000,
	"actualInterestAccured": 0.000000,
	"projectedMaturityAmount": 200.000000,
	"actualMaturityAmount": 0.000000,
	"preClosureAllowed": false,
	"preClosureInterestRate": 0.000000,
	"isLockinPeriodAllowed": false,
	"lockinPeriod": 0,
	"lockinPeriodType": {
		"id": 2,
		"code": "savings.product.lockin.period.type.months",
		"value": "Months"
	},
	"depositEvery": 1,
	"permissions": {
		"rejectAllowed": true,
		"withdrawnByApplicantAllowed": true,
		"undoApprovalAllowed": false,
		"pendingApproval": true,
		"renewelAllowed": false,
		"isMaturedDepositAccount": false,
		"anyActionOnAccountAllowed": true
	},
	"outstandingAmount": 0.000000,
	"savingScheduleData": {
		"currency": {
			"code": "USD",
			"name": "US Dollar",
			"decimalPlaces": 2,
			"displaySymbol": "$",
			"nameCode": "currency.USD",
			"displayLabel": "US Dollar ($)"
		},
		"cumulativeDepositDue": 200.0000,
		"cumulativeDepositPaid": 0.0000,
		"cummulativeInterestAccured": 0.0000,
		"periods": [{
			"period": 1,
			"dueDate": [2013,
			3,
			1],
			"depositDue": 200.0000,
			"depositPaid": 0.0000,
			"interestAccured": 0.0000
		}]
	},
	"transactions": [],
	"interestPostEvery": 3,
	"interestPostFrequency": {
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	}
}

Create a New SavingAccount / Submit a SavingAccount Application

Arguments

command: String Optional, case-insensitive; The default action is to Submit a New SavingAccount Application ("Submitted and awaiting approval" status).

Mandatory Fields

clientId, productId, savingsDepositAmountPerPeriod, tenureMonths, depositEvery, interestCalculationMethod, recurringInterestRate, commencementDate, interestPostEvery

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

POST savingaccount
Content-Type: application/json
Request Body:
{
	"clientId": "17",
	"dateFormat": "dd MMMM yyyy",
	"locale": "en",
	"currencyCode": "ZAR",
	"digitsAfterDecimal": "2",
	"productId": "5",
	"commencementDate": "05 February 2013",
	"externalId": "",
	"savingsDepositAmountPerPeriod": "500",
	"minimumBalanceForWithdrawal": "100",
	"tenure": "12",
	"tenureType": "1",
	"depositEvery": "1",
	"frequency": "2",
	"isLockinPeriodAllowed": "false",
	"isPartialDepositAllowed": "false",
	"interestCalculationMethod": "1",
	"recurringInterestRate": "12",
	"interestType": "2",
	"savingInterestRate": "12",
	"interestPostEvery": "3",
	"interestPostFrequency": "2",
	"lockinPeriod": "0",
	"lockinPeriodType": "2"
}

{
 "resourceId": 42
}

Approval, Reject or Withdraw a SavingAccount Application

Arguments

command: String Mandatory, case-insensitive; 'approve' : Approve SavingAccount; 'reject' : Reject SavingAccount; 'withdrewbyclient' : Client Withdrew SavingAccount Application

Mandatory Fields

eventDate

POST https://Domain Name/api/v1/savingaccounts/{savingaccountId}

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


{
"resourceId": 37
}

Delete a SavingAccount

Note: savingaccount is deleted.

DELETE https://Domain Name/api/v1/savingaccounts/{savingaccountsId}

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

{
"resourceId": 1
}

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

digitsAfterDecimal

Override the currency default value for digitsAfterDecimal.

principal

Loan amount.

inArrearsTolerance

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

numberOfRepayments

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

interestRatePerPeriod

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

repaymentEvery

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

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

repaymentFrequencyType

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

interestRateFrequencyType

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

amortizationType

Example Values: Equal principle payments, Equal installments

interestType

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

interestCalculationPeriodType

Example Values: Same as repayment period, Daily

accountingRule

Example Values:NONE(1), CASH_BASED(2), ACCRUAL_BASED(3)

List Loan Products

Example Requests:

loanproducts

loanproducts?fields=name,description,interestRateFrequencyType,amortizationType


GET https://DomainName/api/v1/loanproducts


[
    {
        "id": 1,
        "name": "A new loan product for me",
        "currency": {
            "code": "USD",
            "name": "US Dollar",
            "decimalPlaces": 2,
            "displaySymbol": "$",
            "nameCode": "currency.USD",
            "displayLabel": "US Dollar ($)"
        },
        "principal": 100000,
        "numberOfRepayments": 12,
        "loanTermFrequency": 12,
        "repaymentEvery": 1,
        "loanTermFrequencyType": {
            "id": 2,
            "code": "loanTermFrequency.periodFrequencyType.months",
            "value": "Months"
        },
        "repaymentFrequencyType": {
            "id": 2,
            "code": "repaymentFrequency.periodFrequencyType.months",
            "value": "Months"
        },
        "transactionProcessingStrategyId": 1,
        "transactionProcessingStrategyName": "Mifos style",
        "interestRatePerPeriod": 1.75,
        "interestRateFrequencyType": {
            "id": 2,
            "code": "interestRateFrequency.periodFrequencyType.months",
            "value": "Per month"
        },
        "annualInterestRate": 21,
        "amortizationType": {
            "id": 1,
            "code": "amortizationType.equal.installments",
            "value": "Equal installments"
        },
        "interestType": {
            "id": 0,
            "code": "interestType.declining.balance",
            "value": "Declining Balance"
        },
        "interestCalculationPeriodType": {
            "id": 1,
            "code": "interestCalculationPeriodType.same.as.repayment.period",
            "value": "Same as repayment period"
        },
        "accountingRule": {
            "id": 1,
            "code": "accountingRuleType.none",
            "value": "NONE"
        }
    }
]

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


{
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "decimalPlaces": 2,
    "displaySymbol": "$",
    "nameCode": "currency.USD",
    "displayLabel": "US Dollar ($)"
  },
  "loanTermFrequencyType": {
    "id": 2,
    "code": "loanTermFrequency.periodFrequencyType.months",
    "value": "Months"
  },
  "repaymentFrequencyType": {
    "id": 2,
    "code": "repaymentFrequency.periodFrequencyType.months",
    "value": "Months"
  },
  "interestRateFrequencyType": {
    "id": 2,
    "code": "interestRateFrequency.periodFrequencyType.months",
    "value": "Per month"
  },
  "amortizationType": {
    "id": 1,
    "code": "amortizationType.equal.installments",
    "value": "Equal installments"
  },
  "interestType": {
    "id": 0,
    "code": "interestType.declining.balance",
    "value": "Declining Balance"
  },
  "interestCalculationPeriodType": {
    "id": 1,
    "code": "interestCalculationPeriodType.same.as.repayment.period",
    "value": "Same as repayment period"
  },
  "accountingRule": 1,
  "currencyOptions": [
    {
      "code": "USD",
      "name": "US Dollar",
      "decimalPlaces": 2,
      "displaySymbol": "$",
      "nameCode": "currency.USD",
      "displayLabel": "US Dollar ($)"
    }
  ],
  "fundOptions": [
    {
      "id": 1,
      "name": "EU Agri Fund"
    }
  ],
  "transactionProcessingStrategyOptions": [
    {
      "id": 1,
      "code": "mifos-standard-strategy",
      "name": "Mifos style"
    },
    {
      "id": 2,
      "code": "heavensfamily-strategy",
      "name": "Heavensfamily"
    },
    {
      "id": 3,
      "code": "creocore-strategy",
      "name": "Creocore"
    },
    {
      "id": 4,
      "code": "rbi-india-strategy",
      "name": "RBI (India)"
    }
  ],
  "amortizationTypeOptions": [
    {
      "id": 1,
      "code": "amortizationType.equal.installments",
      "value": "Equal installments"
    },
    {
      "id": 0,
      "code": "amortizationType.equal.principal",
      "value": "Equal principle payments"
    }
  ],
  "interestTypeOptions": [
    {
      "id": 1,
      "code": "interestType.flat",
      "value": "Flat"
    },
    {
      "id": 0,
      "code": "interestType.declining.balance",
      "value": "Declining Balance"
    }
  ],
  "interestCalculationPeriodTypeOptions": [
    {
      "id": 0,
      "code": "interestCalculationPeriodType.daily",
      "value": "Daily"
    },
    {
      "id": 1,
      "code": "interestCalculationPeriodType.same.as.repayment.period",
      "value": "Same as repayment period"
    }
  ],
  "repaymentFrequencyTypeOptions": [
    {
      "id": 0,
      "code": "repaymentFrequency.periodFrequencyType.days",
      "value": "Days"
    },
    {
      "id": 1,
      "code": "repaymentFrequency.periodFrequencyType.weeks",
      "value": "Weeks"
    },
    {
      "id": 2,
      "code": "repaymentFrequency.periodFrequencyType.months",
      "value": "Months"
    }
  ],
  "interestRateFrequencyTypeOptions": [
    {
      "id": 2,
      "code": "interestRateFrequency.periodFrequencyType.months",
      "value": "Per month"
    },
    {
      "id": 3,
      "code": "interestRateFrequency.periodFrequencyType.years",
      "value": "Per year"
    }
  ],
  "loanTermFrequencyTypeOptions": [
    {
      "id": 0,
      "code": "loanTermFrequency.periodFrequencyType.days",
      "value": "Days"
    },
    {
      "id": 1,
      "code": "loanTermFrequency.periodFrequencyType.weeks",
      "value": "Weeks"
    },
    {
      "id": 2,
      "code": "loanTermFrequency.periodFrequencyType.months",
      "value": "Months"
    },
    {
      "id": 3,
      "code": "loanTermFrequency.periodFrequencyType.years",
      "value": "Years"
    }
  ],
  "chargeOptions": [
    {
      "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"
      }
    }
  ],
  "accountingOptions": {
        "assetAccountOptions": [
            {
                "id": 1,
                "name": "Fund Source For Loans",
                "glCode": "100001",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 1,
                    "code": "accountType.asset",
                    "value": "ASSET"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "Desc"
            },
            {
                "id": 2,
                "name": "Interest Receivable",
                "glCode": "100002",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 1,
                    "code": "accountType.asset",
                    "value": "ASSET"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "Desc"
            },
            {
                "id": 3,
                "name": "Fees Receivable",
                "glCode": "100003",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 1,
                    "code": "accountType.asset",
                    "value": "ASSET"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "Desc"
            },
            {
                "id": 4,
                "name": "Penalties Receivable",
                "glCode": "100004",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 1,
                    "code": "accountType.asset",
                    "value": "ASSET"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "better duddette"
            }
        ],
        "expenseAccountOptions": [
            {
                "id": 5,
                "name": "Written Off Losses",
                "glCode": "500005",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 5,
                    "code": "accountType.expense",
                    "value": "EXPENSE"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "Desc"
            }
        ],
        "incomeAccountOptions": [
            {
                "id": 6,
                "name": "Income from Interest",
                "glCode": "400001",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 4,
                    "code": "accountType.income",
                    "value": "INCOME"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "Desc"
            },
            {
                "id": 7,
                "name": "Income from Fees",
                "glCode": "400002",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 4,
                    "code": "accountType.income",
                    "value": "INCOME"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "Desc"
            },
            {
                "id": 8,
                "name": "Income from Penalties",
                "glCode": "400003",
                "disabled": false,
                "manualEntriesAllowed": true,
                "type": {
                    "id": 4,
                    "code": "accountType.income",
                    "value": "INCOME"
                },
                "usage": {
                    "id": 1,
                    "code": "accountUsage.detail",
                    "value": "DETAIL"
                },
                "description": "Desc"
            }
        ]
  },
  "accountingMappings": {}
}

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": 1,
    "name": "A new loan product for me",
    "currency": {
        "code": "USD",
        "name": "US Dollar",
        "decimalPlaces": 2,
        "displaySymbol": "$",
        "nameCode": "currency.USD",
        "displayLabel": "US Dollar ($)"
    },
    "principal": 100000,
    "numberOfRepayments": 12,
    "loanTermFrequency": 12,
    "repaymentEvery": 1,
    "loanTermFrequencyType": {
        "id": 2,
        "code": "loanTermFrequency.periodFrequencyType.months",
        "value": "Months"
    },
    "repaymentFrequencyType": {
        "id": 2,
        "code": "repaymentFrequency.periodFrequencyType.months",
        "value": "Months"
    },
    "transactionProcessingStrategyId": 1,
    "transactionProcessingStrategyName": "Mifos style",
    "interestRatePerPeriod": 1.75,
    "interestRateFrequencyType": {
        "id": 2,
        "code": "interestRateFrequency.periodFrequencyType.months",
        "value": "Per month"
    },
    "annualInterestRate": 21,
    "amortizationType": {
        "id": 1,
        "code": "amortizationType.equal.installments",
        "value": "Equal installments"
    },
    "interestType": {
        "id": 0,
        "code": "interestType.declining.balance",
        "value": "Declining Balance"
    },
    "interestCalculationPeriodType": {
        "id": 1,
        "code": "interestCalculationPeriodType.same.as.repayment.period",
        "value": "Same as repayment period"
    },
    "accountingRule": 1,
    "charges": []
}

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 rule

Mandatory Fields

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

Additional Mandatory Fields for Cash(2) based accounting

fundSourceAccountId, loanPortfolioAccountId, interestOnLoanAccountId, incomeFromFeeAccountId, incomeFromPenaltyAccountId, writeOffAccountId

Additional Mandatory Fields for Accrual(3) based accounting

fundSourceAccountId, loanPortfolioAccountId, interestOnLoanAccountId, incomeFromFeeAccountId, incomeFromPenaltyAccountId, writeOffAccountId, receivableInterestAccountId, receivableFeeAccountId, receivablePenaltyAccountId


POST https://DomainName/api/v1/loanproducts


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


{ 
	"resourceId": 1 
}


POST loanproducts
Content-Type: application/json 
Request Body:
{
    "name": "A new loan product for me",
    "currencyCode": "USD",
    "locale": "en_GB",
    "digitsAfterDecimal": "2",
    "principal": "100,000.00",
    "numberOfRepayments": "12",
    "repaymentEvery": "1",
    "repaymentFrequencyType": 2,
    "transactionProcessingStrategyId": 1,
    "interestRatePerPeriod": "1.75",
    "interestRateFrequencyType": 2,
    "amortizationType": 1,
    "interestType": 0,
    "interestCalculationPeriodType": 1,
    "accountingRule":"3",
    "fundSourceAccountId":"15",
    "loanPortfolioAccountId":"16",
    "interestOnLoanAccountId":"14",
    "incomeFromFeeAccountId":"13",
    "incomeFromPenaltyAccountId":"12",
    "writeOffAccountId":"11"
}


{ 
	"resourceId": 2 
}


POST loanproducts
Content-Type: application/json 
Request Body:
{
    "name": "A new loan product for me",
    "currencyCode": "USD",
    "locale": "en_GB",
    "digitsAfterDecimal": "2",
    "principal": "100,000.00",
    "numberOfRepayments": "12",
    "repaymentEvery": "1",
    "repaymentFrequencyType": 2,
    "transactionProcessingStrategyId": 1,
    "interestRatePerPeriod": "1.75",
    "interestRateFrequencyType": 2,
    "amortizationType": 1,
    "interestType": 0,
    "interestCalculationPeriodType": 1,
    "accountingRule":"3",
    "fundSourceAccountId":"15",
    "loanPortfolioAccountId":"16",
    "receivableInterestAccountId":"10",
    "receivableFeeAccountId":"9",
    "receivablePenaltyAccountId":"8",
    "interestOnLoanAccountId":"14",
    "incomeFromFeeAccountId":"13",
    "incomeFromPenaltyAccountId":"12",
    "writeOffAccountId":"11"
}


{ 
	"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"
    }
}

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 e.g. maker-checker.

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": {} }

Codes

Code and code values: Codes represent a specific category of data, their code values are a specific instance of that category.

Codes are mostly system defined which means the code itself comes out of the box and cannot be modifed however its code values can be. e.g. 'Customer Identifier', it defaults to a code value of 'Passport' but could be 'Drivers License, National Id' etc

Create a Code

Creates a code. Codes created through api are always 'user defined' and so system defined is marked as false.


POST https://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 
}

Funds

Simple implementation of funds. At present funds can optionally be associated with a Loan.

This information can then be used to produce reports on loans/loan amounts drawn from a fund.

Create a Fund

Creates a fund.


POST https://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 signifigance 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"
}


{
    "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
    }
]

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
}

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" 
}


{
    "officeId": 1,
    "resourceId": 1,
    "changes": {
        "isLoanOfficer": false
    }
}

Charges

Its typical for MFIs to add extra costs to their financial products. There are typically Fees or Penalites.

Charges is what we use to model both fees and penalities. For now charges can only be associated with loan products / loans.

Create/Define a Charge

Define a new charge that can later be associated with loan products or loans.


POST https://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"
}

{ "resourceId": 1 }

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"
        }
    }
]

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"
    }
}

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 }

Deposit Products :

A Deposit product is a template that is used when creating a Fixed Deposit Account.

Field Descriptions

digitsAfterDecimal

Override the currency default value for digitsAfterDecimal.

minimumBalance :

Minimum deposit amount that is required to create a deposit account.

maximumBalance :

The max deposit amount that can be limited to create a deposit account.

interestCompoundedEvery

Interest amount which is accrued or earned during the tenure of the deposit account will be posted to customer as interest as per the selected period in "interestCompoundedEvery" and combination of "interestCompoundedEveryPeriodType"
e.g.Every 1-Month

tenureInMonths

The duration for fixed deposit (in months).
e.g. 12

maturityDefaultInterestRate

Default interest rate for Fixed Deposit product
e.g. 12

maturityMinInterestRate

Minimum supported interest rate for Fixed Deposit product
e.g. 8

maturityMaxInterestRate

Maximum supported interest rate for Fixed Deposit product
e.g. 14

renewalAllowed

Allows to renew the deposit account on maturity
Used like: renewalAllowed:true

preClosureAllowed

Support for pre-closing a Fixed deposit account before maturity
If 'true' : preClosureAllowed else preClosure is not allowed.

preClosureInterestRate

Denotes the interest rate for deposit accounts for pre-closure accounts.
This rate is applicable if the account is pre-closed / Before maturity.

interestCompoundingAllowed

Denotes whether the interest is calculated on compounding basis or not.
if true:interest calculated on compounding basis, else interest calculated on simple calculation basis.

isLockinPeriodAllowed

This will allow to set the lock-in period for a fixed deposit product
If 'true' :isLockinPeriodAllowed otherwise isLockinPeriod not allowed

lockinPeriod

Defines a lock-in period for deposit account.

List DepositProducts

Example Requests:

depositproducts

depositproducts?fields=name, ......

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


[{
	"id": 1,
	"name": "Test",
	"description": "asdf",
	"currencyCode": "USD",
	"digitsAfterDecimal": 2,
	"minimumBalance": 100.000000,
	"maximumBalance": 1000.000000,
	"tenureInMonths": 12,
	"maturityDefaultInterestRate": 12.000000,
	"maturityMinInterestRate": 8.000000,
	"maturityMaxInterestRate": 12.000000,
	"interestCompoundedEvery": 1,
	"interestCompoundedEveryPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"currency": {
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	},
	"renewalAllowed": false,
	"preClosureAllowed": false,
	"preClosureInterestRate": 6.000000,
	"interestCompoundingAllowed": true,
	"isLockinPeriodAllowed": false,
	"lockinPeriod": 2,
	"lockinPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"createdOn": 1360576753000,
	"lastModifedOn": 1360579312000
}...]

Retrieve DepositProduct 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:

depositproducts/template

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


{
	"interestCompoundedEveryPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"currency": {
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	},
	"renewalAllowed": false,
	"preClosureAllowed": false,
	"isLockinPeriodAllowed": false,
	"lockinPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"currencyOptions": [{
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	}],
	"interestCompoundedEveryPeriodTypeOptions": [{
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	}]
}

Retrieve a Deposit Product

Example Requests:

depositproducts/1

depositproducts/1?template=true

depositproducts/1?fields=name,description

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


{
  "id": 1,
  "name": "Test",
  "description": "asdf",
  "currencyCode": "USD",
  "digitsAfterDecimal": 2,
  "minimumBalance": 100,
  "maximumBalance": 1000,
  "tenureInMonths": 12,
  "maturityDefaultInterestRate": 12,
  "maturityMinInterestRate": 8,
  "maturityMaxInterestRate": 12,
  "interestCompoundedEvery": 1,
  "interestCompoundedEveryPeriodType": {
	"id": 2,
	"code": "deposit.interest.compounding.period.periodFrequencyType.months",
	"value": "Months"
  },
  "currency": {
	"code": "USD",
	"name": "US Dollar",
	"decimalPlaces": 2,
	"displaySymbol": "$",
	"nameCode": "currency.USD",
	"displayLabel": "US Dollar ($)"
  },
  "renewalAllowed": false,
  "preClosureAllowed": false,
  "preClosureInterestRate": 6,
  "interestCompoundingAllowed": true,
  "isLockinPeriodAllowed": false,
  "lockinPeriod": 2,
  "lockinPeriodType": {
	"id": 2,
	"code": "deposit.interest.compounding.period.periodFrequencyType.months",
	"value": "Months"
  },
  "createdOn": 1360576753000,
  "lastModifedOn": 1360579312000
}

GET https://Domain Name/api/v1/depositproducts/1?template=true


{
	"id": 1,
	"name": "Test",
	"description": "asdf",
	"currencyCode": "USD",
	"digitsAfterDecimal": 2,
	"minimumBalance": 100.000000,
	"maximumBalance": 1000.000000,
	"tenureInMonths": 12,
	"maturityDefaultInterestRate": 12.000000,
	"maturityMinInterestRate": 8.000000,
	"maturityMaxInterestRate": 12.000000,
	"interestCompoundedEvery": 1,
	"interestCompoundedEveryPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"currency": {
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	},
	"renewalAllowed": false,
	"preClosureAllowed": false,
	"preClosureInterestRate": 6.000000,
	"interestCompoundingAllowed": true,
	"isLockinPeriodAllowed": false,
	"lockinPeriod": 2,
	"lockinPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"createdOn": 1360576753000,
	"lastModifedOn": 1360579312000,
	"currencyOptions": [{
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	}],
	"interestCompoundedEveryPeriodTypeOptions": [{
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	}]
}

Create a Deposit Product

Mandatory Fields

name, currencyCode, digitsAfterDecimal,interestPostedEvery, minimumBalance,

tenureInMonths, maturityDefaultInterestRate,maturityMinInterestRate,

maturityMaxInterestRate,interestCompoundedEvery,preClosureInterestRate.

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

POST depositproducts
Content-Type: application/json
Request Body:
{
	"locale": "en",
	"name": "Test",
	"description": "asdf",
	"currencyCode": "USD",
	"digitsAfterDecimal": "2",
	"minimumBalance": "100",
	"maximumBalance": "1,000",
	"tenureInMonths": "12",
	"renewalAllowed": "true",
	"preClosureAllowed": "false",
	"interestCompoundingAllowed": "true",
	"isLockinPeriodAllowed": "false",
	"maturityDefaultInterestRate": "12",
	"maturityMinInterestRate": "8",
	"maturityMaxInterestRate": "12",
	"preClosureInterestRate": "6",
	"interestCompoundedEvery": "1",
	"interestCompoundedEveryPeriodType": "2",
	"lockinPeriod": "2",
	"lockinPeriodType": "2"
}

{
  "resourceId": 1
}

Update a Deposit Product

PUT https://Domain Name/api/v1/depositproducts/{depositId}

POST depositproducts/1
Content-Type: application/json
Request Body:
{
 "locale": "en",
 "description": "Update desc"
}

{
  "resourceId": 1
}

Delete a Deposit Product

Deletes a Deposit Product.


DELETE https://Domain Name/api/v1/depositproducts/{productId}


DELETE depositproducts/1
Content-Type: application/json

{ "resourceId": 1 }

Saving Products :

A Saving product is a template that is used when creating a Saving Account.

Field Descriptions

digitsAfterDecimal

Override the currency default value for digitsAfterDecimal.

savingsDepositAmount :

The deposit amount need to be deposited every depositEvery period.

minimumBalanceForWithdrawal :

The minimumbal that is need to be maintained in saving account

depositEvery:

The time period to deposit the amount to saving account every "depositEvery" "frequency"
e.g. Every 1 Month

tenureType

This denotes the tenureType for savings account

tenure

The duration for fixed deposit (in months).
e.g. 12

interestRate

Default interest rate for Saving account
e.g. 12

interestType

Denotes the interestType for Saving account
simple/compounding

minInterestRate

Minimum supported interest rate for Saving account
e.g. 8

maxInterestRate

Maximum supported interest rate for Saving account
e.g. 14

isPartialDepositAllowed

Allows to deposit the partial amount for saving account.
Used like: isPartialDepositAllowed:true

isLockinPeriodAllowed

This will allow to set the lock-in period for a saving account
If 'true' :isLockinPeriodAllowed otherwise isLockinPeriod not allowed

lockinPeriod

Defines a lock-in period for saving account.

savingProductType

Defines the savingProductType for saving account.
Recurring/Regular

interestCalculationMethod

Defines the interestCalculationMethod for saving account.
Montly Collection/Average Balance etc

List SavingProducts

Example Requests:

savingproducts

savingproducts?fields=name, ......

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


[{
	"id": 1,
	"name": "Test",
	"currency": {
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	},
	"digitsAfterDecimal": 2,
	"interestRate": 12.000000,
	"minInterestRate": 6.000000,
	"maxInterestRate": 12.000000,
	"savingsDepositAmount": 1000.000000,
	"savingProductType": {
		"id": 1,
		"code": "savings.product.savingProductType.reccuring",
		"value": "Recurring"
	},
	"tenureType": {
		"id": 1,
		"code": "savings.tenure.tenureTypeEnum.fixedPeriod",
		"value": "FixedPeriod"
	},
	"tenure": 12,
	"savingFrequencyType": {
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	},
	"interestType": {
		"id": 2,
		"code": "savings.interest.type.savingsInterestType.compounding",
		"value": "Compounding"
	},
	"interestCalculationMethod": {
		"id": 1,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
		"value": "AverageBalance"
	},
	"minimumBalanceForWithdrawal": 100.000000,
	"isPartialDepositAllowed": false,
	"isLockinPeriodAllowed": false,
	"lockinPeriod": 0,
	"lockinPeriodType": {
		"id": 2,
		"code": "deposit.interest.compounding.period.periodFrequencyType.months",
		"value": "Months"
	},
	"createdOn": 1360594232000,
	"lastModifedOn": 1360594232000,
	"depositEvery": 3
}]

Retrieve SavingProduct 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:

savingproducts/template

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


{
	"currency": {
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	},
	"digitsAfterDecimal": 2,
	"interestRate": 0,
	"savingsDepositAmount": 0,
	"savingProductType": {
		"id": 1,
		"code": "savings.product.savingProductType.reccuring",
		"value": "Recurring"
	},
	"tenureType": {
		"id": 1,
		"code": "savings.tenure.tenureTypeEnum.fixedPeriod",
		"value": "FixedPeriod"
	},
	"tenure": 12,
	"savingFrequencyType": {
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	},
	"interestType": {
		"id": 2,
		"code": "savings.interest.type.savingsInterestType.compounding",
		"value": "Compounding"
	},
	"interestCalculationMethod": {
		"id": 1,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
		"value": "AverageBalance"
	},
	"minimumBalanceForWithdrawal": 100,
	"isPartialDepositAllowed": false,
	"isLockinPeriodAllowed": false,
	"lockinPeriod": 0,
	"lockinPeriodType": {
		"id": 2,
		"code": "savings.product.lockin.period.type.months",
		"value": "Months"
	},
	"createdOn": 1360596667364,
	"lastModifedOn": 1360596667364,
	"depositEvery": 3,
	"currencyOptions": [{
		"code": "USD",
		"name": "US Dollar",
		"decimalPlaces": 2,
		"displaySymbol": "$",
		"nameCode": "currency.USD",
		"displayLabel": "US Dollar ($)"
	}],
	"savingsProductTypeOptions": [{
		"id": 1,
		"code": "savings.product.savingProductType.reccuring",
		"value": "Recurring"
	},
	{
		"id": 2,
		"code": "savings.product.savingProductType.regular",
		"value": "Regular"
	}],
	"tenureTypeOptions": [{
		"id": 1,
		"code": "savings.tenure.tenureTypeEnum.fixedPeriod",
		"value": "FixedPeriod"
	},
	{
		"id": 2,
		"code": "savings.tenure.tenureTypeEnum.perpetual",
		"value": "Perpetual"
	}],
	"savingFrequencyOptions": [{
		"id": 2,
		"code": "saving.product.frequency.period.savingFrequencyType.monthly",
		"value": "Months"
	}],
	"savingsInterestTypeOptions": [{
		"id": 1,
		"code": "savings.interest.type.savingsInterestType.simple",
		"value": "Simple"
	},
	{
		"id": 2,
		"code": "savings.interest.type.savingsInterestType.compounding",
		"value": "Compounding"
	}],
	"lockinPeriodTypeOptions": [{
		"id": 2,
		"code": "savings.product.lockin.period.type.months",
		"value": "Months"
	}],
	"interestCalculationOptions": [{
		"id": 1,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
		"value": "AverageBalance"
	},
	{
		"id": 2,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.minbal",
		"value": "Minimumbalance"
	},
	{
		"id": 3,
		"code": "savings.interestCalculation.method.savinginterest.calculation.method.monthlycllection",
		"value": "MonthlyCollection"
	}]
}

Retrieve a Saving Product

Example Requests:

savingproducts/1

savingproducts/1?template=true

savingproducts/1?fields=name,description

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


{
  "id": 1,
  "name": "Test",
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "decimalPlaces": 2,
    "displaySymbol": "$",
    "nameCode": "currency.USD",
    "displayLabel": "US Dollar ($)"
  },
  "digitsAfterDecimal": 2,
  "interestRate": 12,
  "minInterestRate": 6,
  "maxInterestRate": 12,
  "savingsDepositAmount": 1000,
  "savingProductType": {
    "id": 1,
    "code": "savings.product.savingProductType.reccuring",
    "value": "Recurring"
  },
  "tenureType": {
    "id": 1,
    "code": "savings.tenure.tenureTypeEnum.fixedPeriod",
    "value": "FixedPeriod"
  },
  "tenure": 12,
  "savingFrequencyType": {
    "id": 2,
    "code": "saving.product.frequency.period.savingFrequencyType.monthly",
    "value": "Months"
  },
  "interestType": {
    "id": 2,
    "code": "savings.interest.type.savingsInterestType.compounding",
    "value": "Compounding"
  },
  "interestCalculationMethod": {
    "id": 1,
    "code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
    "value": "AverageBalance"
  },
  "minimumBalanceForWithdrawal": 100,
  "isPartialDepositAllowed": false,
  "isLockinPeriodAllowed": false,
  "lockinPeriod": 0,
  "lockinPeriodType": {
    "id": 2,
    "code": "deposit.interest.compounding.period.periodFrequencyType.months",
    "value": "Months"
  },
  "createdOn": 1360594232000,
  "lastModifedOn": 1360594232000,
  "depositEvery": 3
}

GET https://Domain Name/api/v1/depositproducts/1?template=true


{
  "id": 1,
  "name": "Test",
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "decimalPlaces": 2,
    "displaySymbol": "$",
    "nameCode": "currency.USD",
    "displayLabel": "US Dollar ($)"
  },
  "digitsAfterDecimal": 2,
  "interestRate": 12,
  "minInterestRate": 6,
  "maxInterestRate": 12,
  "savingsDepositAmount": 1000,
  "savingProductType": {
    "id": 1,
    "code": "savings.product.savingProductType.reccuring",
    "value": "Recurring"
  },
  "tenureType": {
    "id": 1,
    "code": "savings.tenure.tenureTypeEnum.fixedPeriod",
    "value": "FixedPeriod"
  },
  "tenure": 12,
  "savingFrequencyType": {
    "id": 2,
    "code": "saving.product.frequency.period.savingFrequencyType.monthly",
    "value": "Months"
  },
  "interestType": {
    "id": 2,
    "code": "savings.interest.type.savingsInterestType.compounding",
    "value": "Compounding"
  },
  "interestCalculationMethod": {
    "id": 1,
    "code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
    "value": "AverageBalance"
  },
  "minimumBalanceForWithdrawal": 100,
  "isPartialDepositAllowed": false,
  "isLockinPeriodAllowed": false,
  "lockinPeriod": 0,
  "lockinPeriodType": {
    "id": 2,
    "code": "deposit.interest.compounding.period.periodFrequencyType.months",
    "value": "Months"
  },
  "createdOn": 1360594232000,
  "lastModifedOn": 1360594232000,
  "depositEvery": 3,
  "currencyOptions": [
    {
      "code": "USD",
      "name": "US Dollar",
      "decimalPlaces": 2,
      "displaySymbol": "$",
      "nameCode": "currency.USD",
      "displayLabel": "US Dollar ($)"
    }
  ],
  "savingsProductTypeOptions": [
    {
      "id": 1,
      "code": "savings.product.savingProductType.reccuring",
      "value": "Recurring"
    },
    {
      "id": 2,
      "code": "savings.product.savingProductType.regular",
      "value": "Regular"
    }
  ],
  "tenureTypeOptions": [
    {
      "id": 1,
      "code": "savings.tenure.tenureTypeEnum.fixedPeriod",
      "value": "FixedPeriod"
    },
    {
      "id": 2,
      "code": "savings.tenure.tenureTypeEnum.perpetual",
      "value": "Perpetual"
    }
  ],
  "savingFrequencyOptions": [
    {
      "id": 2,
      "code": "saving.product.frequency.period.savingFrequencyType.monthly",
      "value": "Months"
    }
  ],
  "savingsInterestTypeOptions": [
    {
      "id": 1,
      "code": "savings.interest.type.savingsInterestType.simple",
      "value": "Simple"
    },
    {
      "id": 2,
      "code": "savings.interest.type.savingsInterestType.compounding",
      "value": "Compounding"
    }
  ],
  "lockinPeriodTypeOptions": [
    {
      "id": 2,
      "code": "savings.product.lockin.period.type.months",
      "value": "Months"
    }
  ],
  "interestCalculationOptions": [
    {
      "id": 1,
      "code": "savings.interestCalculation.method.savinginterest.calculation.method.averagebal",
      "value": "AverageBalance"
    },
    {
      "id": 2,
      "code": "savings.interestCalculation.method.savinginterest.calculation.method.minbal",
      "value": "Minimumbalance"
    },
    {
      "id": 3,
      "code": "savings.interestCalculation.method.savinginterest.calculation.method.monthlycllection",
      "value": "MonthlyCollection"
    }
  ]
}

Create a Saving Product

Mandatory Fields

name, currencyCode, digitsAfterDecimal,interestPostedEvery, minimumBalance,

tenureInMonths, maturityDefaultInterestRate,maturityMinInterestRate,

maturityMaxInterestRate,interestCompoundedEvery,preClosureInterestRate.

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

POST savingproducts
Content-Type: application/json
Request Body:
{
	"locale": "en",
	"interestCalculationMethod": "1",
	"name": "Test",
	"savingProductType": "1",
	"description": "",
	"currencyCode": "USD",
	"digitsAfterDecimal": "2",
	"savingsDepositAmount": "1000",
	"minimumBalanceForWithdrawal": "100",
	"tenure": "12",
	"tenureType": "1",
	"isLockinPeriodAllowed": "false",
	"isPartialDepositAllowed": "false",
	"interestRate": "12",
	"interestType": "2",
	"minInterestRate": "6",
	"maxInterestRate": "12",
	"depositEvery": "3",
	"frequency": "2",
	"lockinPeriod": "0",
	"lockinPeriodType": "2"
}

{
  "resourceId": 1
}

Update a Saving Product

PUT https://Domain Name/api/v1/savingproducts/{depositId}

POST savingproducts/1
Content-Type: application/json
Request Body:
{
 "locale": "en",
 "description": "Update desc"
}

{
  "resourceId": 1
}

Delete a Saving Product

Deletes a Saving Product.


DELETE https://Domain Name/api/v1/savingproducts/{productId}


DELETE savingproducts/1
Content-Type: application/json

{ "resourceId": 1 }

Data Tables

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

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

List Data Tables

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

Arguments

apptable: optional; The Mifos X core application table.

Example Requests:

datatables?apptable=m_client

datatables


GET https://DomainName/api/v1/datatables


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

Register Data Table

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


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


POST datatables/register/userDefinedTableName/m_client 

Content-Type: application/json 
Request Body: 
{}


{ 
	"resourceId": null 
}

Deregister Data Table

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


POST https://DomainName/api/v1/datatables/deregister/{datatable}


POST datatables/deregister/userDefinedTableName 

Content-Type: application/json 
Request Body: 
{}


{
	"resourceId": null
}

Create Entry in Data Table

Adds a row to the data table.

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


POST https://DomainName/api/v1/datatables/{datatable}/{apptableId}


POST datatables/Additional Client Fields Data/1 

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


{
	"resourceId": 1
}

Retrieve Entry(s) from Data Table

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

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

Arguments

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

Example Requests:

datatables/Additional Client Fields Data/1

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

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


GET https://DomainName/api/v1/datatables/{datatable}/{apptableId}


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

Update Entry in Data Table (One to One)

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


PUT https://DomainName/api/v1/datatables/{datatable}/{apptableId}


PUT datatables/Additional Client Fields Data/1 

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

{ "resourceId": 1 }

Update Entry in Data Table (One to Many)

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


PUT https://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/Additional Client Fields Data/1 

Content-Type: application/json 

Request Body:
{}

{ "resourceId": 1 }

Delete Entry in Data Table (One to Many)

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


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


DELETE datatables/Extra Family Details Data/1/2 

Content-Type: application/json 
Request Body: 
{}

{ "resourceId": 1 }

Reports

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

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

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

List Reports

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

Arguments

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

Example Requests:

reports

reports?exportCSV=true


GET https://DomainName/api/v1/reports


{
    "columnHeaders": [
        {
            "columnName": "report_id",
            "columnType": "INT",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        },
        {
            "columnName": "report_name",
            "columnType": "VARCHAR",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        },
        {
            "columnName": "report_type",
            "columnType": "VARCHAR",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        },
        {
            "columnName": "report_subtype",
            "columnType": "VARCHAR",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        },
        {
            "columnName": "report_category",
            "columnType": "VARCHAR",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        },
        {
            "columnName": "parameter_id",
            "columnType": "INT",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        },
        {
            "columnName": "report_parameter_name",
            "columnType": "VARCHAR",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        },
        {
            "columnName": "parameter_name",
            "columnType": "VARCHAR",
            "isColumnNullable": false,
            "isColumnPrimaryKey": false,
            "columnValues": []
        }
    ],
    "data": [
        {
            "row": [
                "10",
                "Active Loans Portfolio Status",
                "Table",
                null,
                "Loan",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "10",
                "Active Loans Portfolio Status",
                "Table",
                null,
                "Loan",
                "6",
                null,
                "loanOfficerIdSelectAll"
            ]
        },
        {
            "row": [
                "10",
                "Active Loans Portfolio Status",
                "Table",
                null,
                "Loan",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "10",
                "Active Loans Portfolio Status",
                "Table",
                null,
                "Loan",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "10",
                "Active Loans Portfolio Status",
                "Table",
                null,
                "Loan",
                "25",
                null,
                "loanProductIdSelectAll"
            ]
        },
        {
            "row": [
                "11",
                "Active Loans Summary per Branch",
                "Table",
                null,
                "Loan Portfolio",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "11",
                "Active Loans Summary per Branch",
                "Table",
                null,
                "Loan Portfolio",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "48",
                "Balance Sheet",
                "Pentaho",
                null,
                "Accounting",
                "5",
                "branch",
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "48",
                "Balance Sheet",
                "Pentaho",
                null,
                "Accounting",
                "41",
                "date",
                "endDateSelect"
            ]
        },
        {
            "row": [
                "1",
                "Client Listing",
                "Table",
                null,
                "Client",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "2",
                "Client Loans Listing",
                "Table",
                null,
                "Client",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "2",
                "Client Loans Listing",
                "Table",
                null,
                "Client",
                "6",
                null,
                "loanOfficerIdSelectAll"
            ]
        },
        {
            "row": [
                "2",
                "Client Loans Listing",
                "Table",
                null,
                "Client",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "2",
                "Client Loans Listing",
                "Table",
                null,
                "Client",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "2",
                "Client Loans Listing",
                "Table",
                null,
                "Client",
                "25",
                null,
                "loanProductIdSelectAll"
            ]
        },
        {
            "row": [
                "20",
                "Funds Disbursed Between Dates Summary",
                "Table",
                null,
                "Fund",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "20",
                "Funds Disbursed Between Dates Summary",
                "Table",
                null,
                "Fund",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "20",
                "Funds Disbursed Between Dates Summary",
                "Table",
                null,
                "Fund",
                "40",
                null,
                "startDateSelect"
            ]
        },
        {
            "row": [
                "20",
                "Funds Disbursed Between Dates Summary",
                "Table",
                null,
                "Fund",
                "41",
                null,
                "endDateSelect"
            ]
        },
        {
            "row": [
                "21",
                "Funds Disbursed Between Dates Summary by Office",
                "Table",
                null,
                "Fund",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "21",
                "Funds Disbursed Between Dates Summary by Office",
                "Table",
                null,
                "Fund",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "21",
                "Funds Disbursed Between Dates Summary by Office",
                "Table",
                null,
                "Fund",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "21",
                "Funds Disbursed Between Dates Summary by Office",
                "Table",
                null,
                "Fund",
                "40",
                null,
                "startDateSelect"
            ]
        },
        {
            "row": [
                "21",
                "Funds Disbursed Between Dates Summary by Office",
                "Table",
                null,
                "Fund",
                "41",
                null,
                "endDateSelect"
            ]
        },
        {
            "row": [
                "49",
                "Income Statement",
                "Pentaho",
                null,
                "Accounting",
                "5",
                "branch",
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "49",
                "Income Statement",
                "Pentaho",
                null,
                "Accounting",
                "40",
                "fromDate",
                "startDateSelect"
            ]
        },
        {
            "row": [
                "49",
                "Income Statement",
                "Pentaho",
                null,
                "Accounting",
                "41",
                "toDate",
                "endDateSelect"
            ]
        },
        {
            "row": [
                "5",
                "Loans Awaiting Disbursal",
                "Table",
                null,
                "Loan Portfolio",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "5",
                "Loans Awaiting Disbursal",
                "Table",
                null,
                "Loan Portfolio",
                "6",
                null,
                "loanOfficerIdSelectAll"
            ]
        },
        {
            "row": [
                "5",
                "Loans Awaiting Disbursal",
                "Table",
                null,
                "Loan Portfolio",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "5",
                "Loans Awaiting Disbursal",
                "Table",
                null,
                "Loan Portfolio",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "5",
                "Loans Awaiting Disbursal",
                "Table",
                null,
                "Loan Portfolio",
                "25",
                null,
                "loanProductIdSelectAll"
            ]
        },
        {
            "row": [
                "6",
                "Loans Awaiting Disbursal Summary",
                "Table",
                null,
                "Loan Portfolio",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "6",
                "Loans Awaiting Disbursal Summary",
                "Table",
                null,
                "Loan Portfolio",
                "6",
                null,
                "loanOfficerIdSelectAll"
            ]
        },
        {
            "row": [
                "6",
                "Loans Awaiting Disbursal Summary",
                "Table",
                null,
                "Loan Portfolio",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "6",
                "Loans Awaiting Disbursal Summary",
                "Table",
                null,
                "Loan Portfolio",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "6",
                "Loans Awaiting Disbursal Summary",
                "Table",
                null,
                "Loan Portfolio",
                "25",
                null,
                "loanProductIdSelectAll"
            ]
        },
        {
            "row": [
                "7",
                "Loans Awaiting Disbursal Summary by Month",
                "Table",
                null,
                "Loan Portfolio",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "7",
                "Loans Awaiting Disbursal Summary by Month",
                "Table",
                null,
                "Loan Portfolio",
                "6",
                null,
                "loanOfficerIdSelectAll"
            ]
        },
        {
            "row": [
                "7",
                "Loans Awaiting Disbursal Summary by Month",
                "Table",
                null,
                "Loan Portfolio",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "7",
                "Loans Awaiting Disbursal Summary by Month",
                "Table",
                null,
                "Loan Portfolio",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "7",
                "Loans Awaiting Disbursal Summary by Month",
                "Table",
                null,
                "Loan Portfolio",
                "25",
                null,
                "loanProductIdSelectAll"
            ]
        },
        {
            "row": [
                "15",
                "Portfolio at Risk",
                "Table",
                null,
                "Loan Portfolio",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "15",
                "Portfolio at Risk",
                "Table",
                null,
                "Loan Portfolio",
                "6",
                null,
                "loanOfficerIdSelectAll"
            ]
        },
        {
            "row": [
                "15",
                "Portfolio at Risk",
                "Table",
                null,
                "Loan Portfolio",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "15",
                "Portfolio at Risk",
                "Table",
                null,
                "Loan Portfolio",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "15",
                "Portfolio at Risk",
                "Table",
                null,
                "Loan Portfolio",
                "25",
                null,
                "loanProductIdSelectAll"
            ]
        },
        {
            "row": [
                "16",
                "Portfolio at Risk by Branch",
                "Table",
                null,
                "Loan Portfolio",
                "5",
                null,
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "16",
                "Portfolio at Risk by Branch",
                "Table",
                null,
                "Loan Portfolio",
                "6",
                null,
                "loanOfficerIdSelectAll"
            ]
        },
        {
            "row": [
                "16",
                "Portfolio at Risk by Branch",
                "Table",
                null,
                "Loan Portfolio",
                "10",
                null,
                "currencyIdSelectAll"
            ]
        },
        {
            "row": [
                "16",
                "Portfolio at Risk by Branch",
                "Table",
                null,
                "Loan Portfolio",
                "20",
                null,
                "fundIdSelectAll"
            ]
        },
        {
            "row": [
                "16",
                "Portfolio at Risk by Branch",
                "Table",
                null,
                "Loan Portfolio",
                "25",
                null,
                "loanProductIdSelectAll"
            ]
        },
        {
            "row": [
                "50",
                "Trial Balance",
                "Pentaho",
                null,
                "Accounting",
                "5",
                "branch",
                "OfficeIdSelectOne"
            ]
        },
        {
            "row": [
                "50",
                "Trial Balance",
                "Pentaho",
                null,
                "Accounting",
                "40",
                "fromDate",
                "startDateSelect"
            ]
        },
        {
            "row": [
                "50",
                "Trial Balance",
                "Pentaho",
                null,
                "Accounting",
                "41",
                "toDate",
                "endDateSelect"
            ]
        }
    ]
}

Running a Report

Runs a report and returns the report output.

Arguments

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

Example Requests:

reports/Client%20Listing?R_officeId=1

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

reports/selectOfficeId?R_officeId=1&parameterType=true

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

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

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

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

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


GET https://DomainName/api/v1/reports/{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 of 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


{
    "username": "mifos",
    "userId": 1,
    "base64EncodedAuthenticationKey": "bWlmb3M6cGFzc3dvcmQ=",
    "authenticated": true,
    "permissions": [
        "ALL_FUNCTIONS"
    ]
}


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


{
    "developerMessage": "Invalid authentication details were passed in api request.",
    "developerDocLink": "https://github.com/keithwoodlock/mifosx/wiki/HTTP-API-Error-codes",
    "httpStatusCode": "401",
    "defaultUserMessage": "Unauthenticated. Please login.",
    "userMessageGlobalisationCode": "error.msg.not.authenticated",
    "errors": []
}

Users

An API capability to support administration of application users.

Retrieve list of users

Example Requests:

users

users?fields=id,username,email,officeName


GET https://DomainName/api/v1/users


[
    {
        "id": 1,
        "username": "mifos",
        "officeId": 1,
        "officeName": "Head Office",
        "firstname": "App",
        "lastname": "Administrator",
        "email": "demomfi@mifos.org"
    }
]

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.

List Application Permissions

Example Requests:

permissions

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
  }
]

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

List General Ledger Accounts

Arguments

type: Integer optional
manualEntriesAllowed: boolean optional
usage: Integer optional
disabled: boolean optional

Example Requests:

glaccounts

glaccounts?type=1&manualEntriesAllowed=true&usage=1&disabled=false


GET https://DomainName/api/v1/glaccounts


[
    {
        "id": 16,
        "name": "Cash",
        "glCode": "100001",
        "disabled": false,
        "manualEntriesAllowed": true,
        "type": {
            "id": 1,
            "code": "accountType.asset",
            "value": "ASSET"
        },
        "usage": {
            "id": 1,
            "code": "accountUsage.detail",
            "value": "DETAIL"
        },
        "description": "Desc"
    },
    {
        "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"
    }
]

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


GET https://DomainName/api/v1/glaccounts/template


{
    "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"
        }
    ]
}

Retrieve a General Ledger Account

Example Requests:

glaccounts/1

glaccounts/1?template=true

glaccounts/1?fields=name,glCode


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"
}

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,
    "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

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

List Journal Entries

Arguments

officeId: Integer optional
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: Date (yyyy-MM-dd)optional; Filters for Journal entries whose entry Date is greater than or equal to the passed in Date
toDate: Date (yyyy-MM-dd)optional; Filters for Journal entries whose entry Date is lesser than or equal to the passed in Date
transactionId: String optional

Example Requests:

journalentries?transactionId=PB37X8Y21EQUY4S

journalentries?officeId=1&glAccountId=17&manualEntriesOnly=true&fromDate=2012-01-01&toDate=2013-01-01


GET https://DomainName/api/v1/journalentries?transactionId=PB37X8Y21EQUY4S


[
    {
        "id": 81,
        "officeId": 1,
        "officeName": "Head Office",
        "glAccountName": "Something totally else",
        "glAccountId": 17,
        "glAccountCode": "340098",
        "glAccountType": {
            "id": 3,
            "code": "accountType.equity",
            "value": "EQUITY"
        },
        "transactionDate": [
            2012,
            12,
            12
        ],
        "entryType": {
            "id": 2,
            "code": "journalEntrytType.debit",
            "value": "DEBIT"
        },
        "amount": 120,
        "transactionId": "PB37X8Y21EQUY4S",
        "manualEntry": true,
        "createdByUserId": 1,
        "createdDate": [
            2012,
            12,
            13
        ],
        "createdByUserName": "mifos",
        "reversed": true
    },
    {
        "id": 82,
        "officeId": 1,
        "officeName": "Head Office",
        "glAccountName": "Something else",
        "glAccountId": 19,
        "glAccountCode": "560050",
        "glAccountType": {
            "id": 3,
            "code": "accountType.equity",
            "value": "EQUITY"
        },
        "transactionDate": [
            2012,
            12,
            12
        ],
        "entryType": {
            "id": 1,
            "code": "journalEntryType.credit",
            "value": "CREDIT"
        },
        "amount": 120,
        "transactionId": "PB37X8Y21EQUY4S",
        "manualEntry": true,
        "createdByUserId": 1,
        "createdDate": [
            2012,
            12,
            13
        ],
        "createdByUserName": "mifos",
        "reversed": true
    }
]

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" ,
"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"
}

Retrieve a single Entry

Example Requests:

journalentries/1

journalentries/1?fields=officeName,glAccountId,entryType,amount


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"
}

Overview

Client

Group

Loan

Org

System

Non-Core

Report

User

Template

Savings

Accounting