Mifos X API Documentation

The Mifos X API is organized around REST. Our API is designed to have predictable, resource-oriented URLs, to use HTTP response codes to indicate API errors, and to use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON will be returned in all responses from the API, including errors.

Much of the presentation ideas here have been taken from the very good API reference (https://stripe.com/docs/api)

Try The API From Your Browser

GET (read) examples can be run directly from this documentation. If you want to check out the POST, PUT and DELETE (update) examples a good approach is 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. https://localhost:8443/mifosng-provider/api/v1/offices)
Add a header to indicate you are sending JSON data as part of the request body (e.g. Content-Type: application/json)
Paste the example JSON into a Request Body
Send the Request (and recieve a Response)

Generic Options

Convenience Templates

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

Field Defaults
Allowed Value Lists

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

Restrict Returned Fields

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

Example Request:

https://localhost:8443/mifosng-provider/api/v1/offices/1?pretty=true&fields=id,name,parentName

Pretty JSON Formatting

Parameter "pretty=true" can be used to display JSON from GET requests in an easily readable format. This parameter is used in this documentation so that GET requests are immediately viewable.

If you want easily readable JSON output for POSTs, PUTs and DELETEs it will available in the REST plugin you use e.g. RESTClient for FireFox

Updating Dates and Numbers

Dates

Put in thing about suppying date_format and 'Formatted' being added onto end of field

Numbers

Put in whatever happens to numbers here.

Authentication Overview

JPW: Keith, this needs to change to whatever is right after authentication has been added. Don't know if you will go with keys or passwords (I assume passwords)... but can you fix it so we have one user or one user per role that doesn't need a password or always has a password of 'password' so we can let ppl do stuff from the browser and/or REST plugins? We can talk about this.

STRIPE content: You authenticate to the Mifos X API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

curl https://api.stripe.com/api/v1/charges \
        -u vtUQeOtUnYr7PGCLQ96Ul4zqpDUO4sOE:

JPW: We'll update this after... curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password). A sample test API key has been provided in all the examples on the page, so you can test out any example right away.

Errors

JPW:Need to update this Stripe uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Stripe's servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g. a card is declined), we return a 402 error code.

All errors return JSON with a type (one of card_error, invalid_request_error, or api_error) and message describing the particular problem.

Attributes

type: The type of error returned (card_error, invalid_request_error, api_error) Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can't be charged for some reason. Invalid request errors arise when your request has invalid parameters. API errors cover any other type of problem (e.g. a temporary problem with Stripe's servers) and should turn up only very infrequently.
message: A user-friendly message describing the error
code: optional; For card errors, additional information about the user-friendly message to display for this error (e.g. "Your card was declined.")
param: optional; The parameter the error relates to if the error is parameter-specific. You can use this to display a message near the correct form field, for example.

HTTP Status Code Summary

200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but request failed.
404 Not Found - The requested item doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on Stripe's end.

Errors

Invalid Request Errors Type: invalid_request_error API Errors Type: api_error Card Errors Type: card_error

Code	Details
invalid_number	The card number is invalid
incorrect_number	The card number is incorrect
invalid_expiry_month	The card's expiration month is invalid
invalid_expiry_year	The card's expiration year is invalid
invalid_cvc	The card's security code is invalid
expired_card	The card has expired
invalid_amount	An invalid amount was entered
incorrect_cvc	The card's security code is incorrect
card_declined	The card was declined.
missing	There is no card on a customer that is being charged.
duplicate_transaction	A transaction with identical amount and credit card information was submitted very recently.
processing_error	An error occurred while processing the card.

Clients

Clients ...

Attributes

id: string jpw ipsum as an example of showing the (at least important) columns
amount: blah; blah
card

List Clients

Example Request: https://localhost:8443/mifosng-provider/api/v1/clients

GET https://thedomainname/api/v1/clients

{
  "clients": [
    {
      "organisationId": 1,
      "organisationName": "Demo MFI",
      "officeId": 2,
      "officeName": "sub branch 1",
      "id": 14,
      "firstname": "Patrick",
      "lastname": "Asare-Frimpong",
      "displayName": "Patrick Asare-Frimpong",
      "externalId": null,
      "joinedDate": "2012-04-18",
      "allowedOffices": [],
      "maxJoinedOnOffsetFromToday": -34
    },
    ...
    ...
    {
      "organisationId": 1,
      "organisationName": "Demo MFI",
      "officeId": 1,
      "officeName": "Demo MFI Head Office",
      "id": 17,
      "firstname": "Fred",
      "lastname": "Ziffle",
      "displayName": "Fred Ziffle",
      "externalId": null,
      "joinedDate": "2012-04-21",
      "allowedOffices": [],
      "maxJoinedOnOffsetFromToday": -31
    }
  ]
}

Retrieve Client Details Template

Returns a template that contains the client fields and allowed value lists. This helps build a maintenance User Interface.

Example Request: https://localhost:8443/mifosng-provider/api/v1/clients/template

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

{
  "organisationId": 1,
  "organisationName": null,
  "officeId": 1,
  "officeName": null,
  "id": -1,
  "firstname": "",
  "lastname": "",
  "displayName": "",
  "externalId": null,
  "joinedDate": "2012-05-22",
  "allowedOffices": [
    {
      "id": 1,
      "name": "Demo MFI Head Office",
      "externalId": "1",
      "openingDate": "2009-01-01",
      "hierarchy": ".",
      "parentName": null,
      "parentId": 0,
      "allowedParents": []
    },
    {
      "id": 2,
      "name": "sub branch 1",
      "externalId": "2",
      "openingDate": "2012-01-02",
      "hierarchy": ".2.",
      "parentName": "Demo MFI Head Office",
      "parentId": 1,
      "allowedParents": []
    }
  ],
  "maxJoinedOnOffsetFromToday": 0
}

Retrieve a Client

Returns client fields. It also returns allowed value lists which help build a maintenance User Interface.

Example Request: https://localhost:8443/mifosng-provider/api/v1/clients/1

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

{
  "organisationId": 1,
  "organisationName": "Demo MFI",
  "officeId": 1,
  "officeName": "Demo MFI Head Office",
  "id": 1,
  "firstname": "Patrick",
  "lastname": "O'Meara",
  "displayName": "Patrick O'Meara",
  "externalId": null,
  "joinedDate": "2009-01-04",
  "allowedOffices": [],
  "maxJoinedOnOffsetFromToday": -1234
}

Create a Client

POST https://thedomainname/api/v1/clients

https://localhost:8443/mifosng-provider/api/v1/clients
Content-Type: application/json
Request Body:
{
  "officeId": 1,
  "firstname": "Firstname",
  "lastname": "Surname",
  "externalId": null,
  "dateFormat": "dd MMMM yyyy",
  "joiningDateFormatted": "04 March 2009"
}

{ "entityId": 2}

Update a Client

PUT https://thedomainname/api/v1/clients/1

PUT https://localhost:8443/mifosng-provider/api/v1/clients/1
Content-Type: application/json
Request Body:
{
  "officeId": 1,
  "firstname": "Firstname",
  "lastname": "Surname",
  "externalId": null,
  "dateFormat": "dd MMMM yyyy",
  "joiningDateFormatted": "04 March 2009"
}

{ "entityId": 2}

Retrieve a Client's Loan Account Summary

Example Request: https://localhost:8443/mifosng-provider/api/v1/clients/1/loans

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

{
  "pendingApprovalLoans": [],
  "awaitingDisbursalLoans": [
    {
      "id": 17,
      "externalId": null,
      "loanProductId": 1,
      "loanProductName": "Agricultural Loan",
      "loanStatusId": 200,
      "pendingApproval": false,
      "waitingForDisbursal": true,
      "open": false,
      "closed": false,
      "lifeCycleStatusText": "Approved",
      "lifeCycleStatusDate": null
    }
  ],
  "openLoans": [],
  "closedLoans": [
    {
      "id": 1,
      "externalId": null,
      "loanProductId": 1,
      "loanProductName": "Agricultural Loan",
      "loanStatusId": 600,
      "pendingApproval": false,
      "waitingForDisbursal": false,
      "open": false,
      "closed": true,
      "lifeCycleStatusText": "Closed",
      "lifeCycleStatusDate": null
    }
  ],
  "anyLoanCount": 2,
  "pendingApprovalLoanCount": 0,
  "awaitingDisbursalLoanCount": 1,
  "activeLoanCount": 0,
  "closedLoanCount": 1
}

Retrieve a Client's Notes

Example Request: https://localhost:8443/mifosng-provider/api/v1/clients/2/notes

GET https://thedomainname/api/v1/clients/{clientId}/notes

{
  "notes": [
    {
      "id": 20,
      "clientId": 2,
      "loanId": 0,
      "loanTransactionId": 0,
      "noteTypeId": 100,
      "note": "This is an extra note!",
      "createdById": 2,
      "createdByUsername": "super1",
      "createdOn": "2012-04-22T13:50:25.000+01:00",
      "updatedById": 2,
      "updatedByUsername": "super1",
      "updatedOn": "2012-04-22T13:50:25.000+01:00"
    },
    {
      "id": 16,
      "clientId": 2,
      "loanId": 0,
      "loanTransactionId": 0,
      "noteTypeId": 100,
      "note": "loan only 1/2 amount expected\r\nyes",
      "createdById": 2,
      "createdByUsername": "super1",
      "createdOn": "2012-04-18T15:15:04.000+01:00",
      "updatedById": 2,
      "updatedByUsername": "super1",
      "updatedOn": "2012-04-23T09:38:13.000+01:00"
    }
  ]
}

Add a Client Note

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

POST https://localhost:8443/mifosng-provider/api/v1/clients/1/notes
Content-Type: application/json
Request Body:
{
"note": "a note about the client"
}

{ "entityId": 40}

Retrieve a Client Note

Example Request: https://localhost:8443/mifosng-provider/api/v1/clients/1/notes/40

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

{
  "id": 40,
  "clientId": 2,
  "loanId": 0,
  "loanTransactionId": 0,
  "noteTypeId": 100,
  "note": "a note about the client",
  "createdById": 1,
  "createdByUsername": "mifos",
  "createdOn": "2012-05-22T21:40:05.000+01:00",
  "updatedById": 1,
  "updatedByUsername": "mifos",
  "updatedOn": "2012-05-22T21:40:05.000+01:00"
}

Update a Client Note

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

PUT https://localhost:8443/mifosng-provider/api/v1/clients/1/notes/40
Content-Type: application/json
Request Body:
{
"note": "an updated note about the client"
}

{"entityId": 40}

Loans

Loan stuff.

Attributes

id: string jpw ipsum as an example of showing the (at least important) columns
amount: blah; blah
card

Retrieve Loan Details Template

Returns a template that contains client and loan product fields and allowed value lists. This helps build a maintenance User Interface.

Arguments

clientId: Integer; The 'id' of the Client
productId: Integer; The 'id' of the Loan Product

Example Request: https://localhost:8443/mifosng-provider/api/v1/loans/template?clientId=1&productId=1

GET https://thedomainname/api/v1/loans/template


{
  "organisationId": 1,
  "organisationName": "Demo MFI",
  "clientId": 1,
  "clientName": "Patrick O'Meara",
  "productId": 1,
  "productName": "Agricultural Loan",
  "allowedProducts": [
    {
      "id": 1,
      "name": "Agricultural Loan",
      "description": "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
      "principalMoney": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 100000,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "100000 CFA"
      },
      "interestRatePerPeriod": 1.75,
      "interestRatePeriod": 2,
      "annualInterestRate": 21,
      "interestMethod": 0,
      "interestRateCalculatedInPeriod": 1,
      "numberOfInterestFreePeriods": 0,
      "repaidEvery": 12,
      "repaymentPeriodFrequency": 2,
      "numberOfRepayments": 1,
      "amortizationMethod": 1,
      "inArrearsTolerance": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 1000,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "1000 CFA"
      },
      "createdOn": "2012-04-12T00:00:00.000+01:00",
      "lastModifedOn": "2012-04-12T00:00:00.000+01:00",
      "possibleCurrencies": [],
      "possibleAmortizationOptions": [],
      "possibleInterestOptions": [],
      "possibleInterestRateCalculatedInPeriodOptions": [],
      "repaymentFrequencyOptions": [],
      "interestFrequencyOptions": [],
      "interestRebateAllowed": false,
      "flexible": false
    },
    {
      "id": 2,
      "name": "Brunei Loan",
      "description": null,
      "principalMoney": {
        "currencyCode": "BND",
        "currencyDigitsAfterDecimal": 2,
        "amount": 76000,
        "defaultName": "Brunei Dollar",
        "nameCode": "currency.BND",
        "displaySymbol": "BND",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "76000.00 BND"
      },
      "interestRatePerPeriod": 6,
      "interestRatePeriod": 2,
      "annualInterestRate": 72,
      "interestMethod": 0,
      "interestRateCalculatedInPeriod": 1,
      "numberOfInterestFreePeriods": 0,
      "repaidEvery": 1,
      "repaymentPeriodFrequency": 1,
      "numberOfRepayments": 10,
      "amortizationMethod": 1,
      "inArrearsTolerance": {
        "currencyCode": "BND",
        "currencyDigitsAfterDecimal": 2,
        "amount": 50,
        "defaultName": "Brunei Dollar",
        "nameCode": "currency.BND",
        "displaySymbol": "BND",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "50.00 BND"
      },
      "createdOn": "2012-04-16T00:00:00.000+01:00",
      "lastModifedOn": "2012-04-16T00:00:00.000+01:00",
      "possibleCurrencies": [],
      "possibleAmortizationOptions": [],
      "possibleInterestOptions": [],
      "possibleInterestRateCalculatedInPeriodOptions": [],
      "repaymentFrequencyOptions": [],
      "interestFrequencyOptions": [],
      "interestRebateAllowed": false,
      "flexible": false
    },
    {
      "id": 3,
      "name": "IL Loan",
      "description": null,
      "principalMoney": {
        "currencyCode": "USD",
        "currencyDigitsAfterDecimal": 2,
        "amount": 5000,
        "defaultName": "US Dollar",
        "nameCode": "currency.USD",
        "displaySymbol": "$",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "5000.00 $"
      },
      "interestRatePerPeriod": 15.6,
      "interestRatePeriod": 3,
      "annualInterestRate": 15.6,
      "interestMethod": 1,
      "interestRateCalculatedInPeriod": 1,
      "numberOfInterestFreePeriods": 0,
      "repaidEvery": 1,
      "repaymentPeriodFrequency": 2,
      "numberOfRepayments": 12,
      "amortizationMethod": 1,
      "inArrearsTolerance": {
        "currencyCode": "USD",
        "currencyDigitsAfterDecimal": 2,
        "amount": 0,
        "defaultName": "US Dollar",
        "nameCode": "currency.USD",
        "displaySymbol": "$",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0.00 $"
      },
      "createdOn": "2012-04-18T00:00:00.000+01:00",
      "lastModifedOn": "2012-04-18T00:00:00.000+01:00",
      "possibleCurrencies": [],
      "possibleAmortizationOptions": [],
      "possibleInterestOptions": [],
      "possibleInterestRateCalculatedInPeriodOptions": [],
      "repaymentFrequencyOptions": [],
      "interestFrequencyOptions": [],
      "interestRebateAllowed": false,
      "flexible": false
    },
    {
      "id": 4,
      "name": "IBL Mabeshte",
      "description": "Individual loan",
      "principalMoney": {
        "currencyCode": "KES",
        "currencyDigitsAfterDecimal": 2,
        "amount": 5000,
        "defaultName": "Kenyan Shilling",
        "nameCode": "currency.KES",
        "displaySymbol": "KSh",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "5000.00 KSh"
      },
      "interestRatePerPeriod": 2,
      "interestRatePeriod": 2,
      "annualInterestRate": 24,
      "interestMethod": 1,
      "interestRateCalculatedInPeriod": 1,
      "numberOfInterestFreePeriods": 0,
      "repaidEvery": 12,
      "repaymentPeriodFrequency": 2,
      "numberOfRepayments": 12,
      "amortizationMethod": 1,
      "inArrearsTolerance": {
        "currencyCode": "KES",
        "currencyDigitsAfterDecimal": 2,
        "amount": 0,
        "defaultName": "Kenyan Shilling",
        "nameCode": "currency.KES",
        "displaySymbol": "KSh",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0.00 KSh"
      },
      "createdOn": "2012-04-21T00:00:00.000+01:00",
      "lastModifedOn": "2012-04-21T00:00:00.000+01:00",
      "possibleCurrencies": [],
      "possibleAmortizationOptions": [],
      "possibleInterestOptions": [],
      "possibleInterestRateCalculatedInPeriodOptions": [],
      "repaymentFrequencyOptions": [],
      "interestFrequencyOptions": [],
      "interestRebateAllowed": false,
      "flexible": false
    },
    {
      "id": 5,
      "name": "Salary Loan",
      "description": "Loan for salaried workers",
      "principalMoney": {
        "currencyCode": "GHC",
        "currencyDigitsAfterDecimal": 2,
        "amount": 500,
        "defaultName": "Ghana Cedi",
        "nameCode": "currency.GHC",
        "displaySymbol": "GHC",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "500.00 GHC"
      },
      "interestRatePerPeriod": 3.5,
      "interestRatePeriod": 2,
      "annualInterestRate": 42,
      "interestMethod": 1,
      "interestRateCalculatedInPeriod": 1,
      "numberOfInterestFreePeriods": 0,
      "repaidEvery": 1,
      "repaymentPeriodFrequency": 2,
      "numberOfRepayments": 12,
      "amortizationMethod": 1,
      "inArrearsTolerance": {
        "currencyCode": "GHC",
        "currencyDigitsAfterDecimal": 2,
        "amount": 0,
        "defaultName": "Ghana Cedi",
        "nameCode": "currency.GHC",
        "displaySymbol": "GHC",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0.00 GHC"
      },
      "createdOn": "2012-04-24T00:00:00.000+01:00",
      "lastModifedOn": "2012-04-24T00:00:00.000+01:00",
      "possibleCurrencies": [],
      "possibleAmortizationOptions": [],
      "possibleInterestOptions": [],
      "possibleInterestRateCalculatedInPeriodOptions": [],
      "repaymentFrequencyOptions": [],
      "interestFrequencyOptions": [],
      "interestRebateAllowed": false,
      "flexible": false
    },
    {
      "id": 6,
      "name": "daily-declining-balance",
      "description": "an example loan product based on description for daily declining balance as given by Hugo technologies.",
      "principalMoney": {
        "currencyCode": "USD",
        "currencyDigitsAfterDecimal": 2,
        "amount": 100000,
        "defaultName": "US Dollar",
        "nameCode": "currency.USD",
        "displaySymbol": "$",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "100000.00 $"
      },
      "interestRatePerPeriod": 2,
      "interestRatePeriod": 2,
      "annualInterestRate": 24,
      "interestMethod": 0,
      "interestRateCalculatedInPeriod": 0,
      "numberOfInterestFreePeriods": 0,
      "repaidEvery": 1,
      "repaymentPeriodFrequency": 2,
      "numberOfRepayments": 12,
      "amortizationMethod": 1,
      "inArrearsTolerance": {
        "currencyCode": "USD",
        "currencyDigitsAfterDecimal": 2,
        "amount": 0,
        "defaultName": "US Dollar",
        "nameCode": "currency.USD",
        "displaySymbol": "$",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0.00 $"
      },
      "createdOn": "2012-05-01T00:00:00.000+01:00",
      "lastModifedOn": "2012-05-01T00:00:00.000+01:00",
      "possibleCurrencies": [],
      "possibleAmortizationOptions": [],
      "possibleInterestOptions": [],
      "possibleInterestRateCalculatedInPeriodOptions": [],
      "repaymentFrequencyOptions": [],
      "interestFrequencyOptions": [],
      "interestRebateAllowed": false,
      "flexible": false
    },
    {
      "id": 7,
      "name": "New kind of Loan",
      "description": "A description not exceeding 500 characters.",
      "principalMoney": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 100000,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "100000 CFA"
      },
      "interestRatePerPeriod": 1.75,
      "interestRatePeriod": 2,
      "annualInterestRate": 21,
      "interestMethod": 0,
      "interestRateCalculatedInPeriod": 1,
      "numberOfInterestFreePeriods": 0,
      "repaidEvery": 1,
      "repaymentPeriodFrequency": 2,
      "numberOfRepayments": 1,
      "amortizationMethod": 1,
      "inArrearsTolerance": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 1000,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "1000 CFA"
      },
      "createdOn": "2012-05-21T00:00:00.000+01:00",
      "lastModifedOn": "2012-05-21T00:00:00.000+01:00",
      "possibleCurrencies": [],
      "possibleAmortizationOptions": [],
      "possibleInterestOptions": [],
      "possibleInterestRateCalculatedInPeriodOptions": [],
      "repaymentFrequencyOptions": [],
      "interestFrequencyOptions": [],
      "interestRebateAllowed": false,
      "flexible": false
    }
  ],
  "dateFormat": null,
  "submittedOnDateFormatted": null,
  "submittedOnDate": null,
  "submittedOnNote": "",
  "expectedDisbursementDateFormatted": null,
  "expectedDisbursementDate": "2012-05-22",
  "repaymentsStartingFromDateFormatted": null,
  "repaymentsStartingFromDate": null,
  "interestCalculatedFromDateFormatted": null,
  "interestCalculatedFromDate": null,
  "repaymentSchedule": null,
  "selectedProduct": {
    "id": 1,
    "name": "Agricultural Loan",
    "description": "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
    "principalMoney": {
      "currencyCode": "XOF",
      "currencyDigitsAfterDecimal": 0,
      "amount": 100000,
      "defaultName": "CFA Franc BCEAO",
      "nameCode": "currency.XOF",
      "displaySymbol": "CFA",
      "zero": false,
      "greaterThanZero": true,
      "displaySymbolValue": "100000 CFA"
    },
    "interestRatePerPeriod": 1.75,
    "interestRatePeriod": 2,
    "annualInterestRate": 21,
    "interestMethod": 0,
    "interestRateCalculatedInPeriod": 1,
    "numberOfInterestFreePeriods": 0,
    "repaidEvery": 12,
    "repaymentPeriodFrequency": 2,
    "numberOfRepayments": 1,
    "amortizationMethod": 1,
    "inArrearsTolerance": {
      "currencyCode": "XOF",
      "currencyDigitsAfterDecimal": 0,
      "amount": 1000,
      "defaultName": "CFA Franc BCEAO",
      "nameCode": "currency.XOF",
      "displaySymbol": "CFA",
      "zero": false,
      "greaterThanZero": true,
      "displaySymbolValue": "1000 CFA"
    },
    "createdOn": "2012-04-12T00:00:00.000+01:00",
    "lastModifedOn": "2012-04-12T00:00:00.000+01:00",
    "possibleCurrencies": [
      {
        "code": "GBP",
        "name": "Pound Sterling",
        "decimalPlaces": 2,
        "displaySymbol": null,
        "nameCode": "currency.GBP",
        "displayLabel": "Pound Sterling [GBP]"
      },
      {
        "code": "USD",
        "name": "US Dollar",
        "decimalPlaces": 2,
        "displaySymbol": "$",
        "nameCode": "currency.USD",
        "displayLabel": "US Dollar ($)"
      }
    ],
    "possibleAmortizationOptions": [
      {
        "id": 1,
        "value": "Equal installments"
      },
      {
        "id": 0,
        "value": "Equal principle payments"
      }
    ],
    "possibleInterestOptions": [
      {
        "id": 0,
        "value": "Declining Balance"
      },
      {
        "id": 1,
        "value": "Flat"
      }
    ],
    "possibleInterestRateCalculatedInPeriodOptions": [
      {
        "id": 0,
        "value": "Daily"
      },
      {
        "id": 1,
        "value": "Same as repayment period"
      }
    ],
    "repaymentFrequencyOptions": [
      {
        "id": 0,
        "value": "Days"
      },
      {
        "id": 1,
        "value": "Weeks"
      },
      {
        "id": 2,
        "value": "Months"
      }
    ],
    "interestFrequencyOptions": [
      {
        "id": 2,
        "value": "Per month"
      },
      {
        "id": 3,
        "value": "Per year"
      }
    ],
  }
}

Retrieve a Loan

Returns loan fields.

Example Request: https://localhost:8443/mifosng-provider/api/v1/loans/1

GET https://thedomainname/api/v1/loans/{loanId}

{
  "open": false,
  "openWithRepaymentMade": false,
  "closed": true,
  "interestRebateOutstanding": false,
  "pendingApproval": false,
  "waitingForDisbursal": false,
  "lifeCycleStatusText": "Closed",
  "lifeCycleStatusDate": "2009-11-13",
  "id": 1,
  "externalId": null,
  "loanProductName": "Agricultural Loan",
  "submittedOnDate": "2009-01-05",
  "approvedOnDate": "2009-01-08",
  "expectedDisbursementDate": "2009-01-15",
  "actualDisbursementDate": "2009-01-15",
  "undoDisbursalAllowed": false,
  "expectedFirstRepaymentOnDate": null,
  "interestCalculatedFromDate": null,
  "closedOnDate": "2009-11-13",
  "expectedMaturityDate": "2009-11-15",
  "principal": {
    "currencyCode": "XOF",
    "currencyDigitsAfterDecimal": 0,
    "amount": 100000,
    "defaultName": "CFA Franc BCEAO",
    "nameCode": "currency.XOF",
    "displaySymbol": "CFA",
    "zero": false,
    "greaterThanZero": true,
    "displaySymbolValue": "100000 CFA"
  },
  "interestRatePerYear": 21,
  "interestRatePerPeriod": 1.75,
  "interestPeriodFrequencyType": 2,
  "interestPeriodFrequencyText": "MONTHS",
  "interestMethodType": 0,
  "interestMethodText": "DECLINING_BALANCE",
  "amortizationMethodValue": 1,
  "amortizationMethodText": "EQUAL_INSTALLMENTS",
  "numberOfRepayments": 1,
  "repaymentFrequencyNumber": 10,
  "repaymentFrequencyTypeEnumOrdinal": 2,
  "repaymentFrequencyTypeText": "MONTHS",
  "interestRebateOwed": {
    "currencyCode": "XOF",
    "currencyDigitsAfterDecimal": 0,
    "amount": 0,
    "defaultName": "CFA Franc BCEAO",
    "nameCode": "currency.XOF",
    "displaySymbol": "CFA",
    "zero": true,
    "greaterThanZero": false,
    "displaySymbolValue": "0 CFA"
  },
  "loanData": {
    "repaymentSchedule": {
      "periods": [
        {
          "period": 1,
          "date": "2009-11-15",
          "disbursed": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 0,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": true,
            "greaterThanZero": false,
            "displaySymbolValue": "0 CFA"
          },
          "principal": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 100000,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": false,
            "greaterThanZero": true,
            "displaySymbolValue": "100000 CFA"
          },
          "principalPaid": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 100000,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": false,
            "greaterThanZero": true,
            "displaySymbolValue": "100000 CFA"
          },
          "principalOutstanding": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 0,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": true,
            "greaterThanZero": false,
            "displaySymbolValue": "0 CFA"
          },
          "interest": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 17500,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": false,
            "greaterThanZero": true,
            "displaySymbolValue": "17500 CFA"
          },
          "interestPaid": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 17500,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": false,
            "greaterThanZero": true,
            "displaySymbolValue": "17500 CFA"
          },
          "interestOutstanding": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 0,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": true,
            "greaterThanZero": false,
            "displaySymbolValue": "0 CFA"
          },
          "total": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 117500,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": false,
            "greaterThanZero": true,
            "displaySymbolValue": "117500 CFA"
          },
          "totalPaid": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 117500,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": false,
            "greaterThanZero": true,
            "displaySymbolValue": "117500 CFA"
          },
          "totalOutstanding": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 0,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": true,
            "greaterThanZero": false,
            "displaySymbolValue": "0 CFA"
          },
          "totalWaived": null,
          "totalArrears": {
            "currencyCode": "XOF",
            "currencyDigitsAfterDecimal": 0,
            "amount": 0,
            "defaultName": "CFA Franc BCEAO",
            "nameCode": "currency.XOF",
            "displaySymbol": "CFA",
            "zero": true,
            "greaterThanZero": false,
            "displaySymbolValue": "0 CFA"
          },
          "arrearsFrom": null,
          "arrearsTo": null,
          "paidInFullOn": "2009-11-13",
          "lastAffectingPaymentOn": "2009-11-13",
          "fullyPaid": true
        }
      ]
    },
    "summary": {
      "originalPrincipal": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 100000,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "100000 CFA"
      },
      "originalInterest": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 17500,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "17500 CFA"
      },
      "originalTotal": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 117500,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "117500 CFA"
      },
      "principalPaid": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 100000,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "100000 CFA"
      },
      "principalOutstanding": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 0,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0 CFA"
      },
      "interestPaid": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 17500,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "17500 CFA"
      },
      "interestOutstanding": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 0,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0 CFA"
      },
      "totalPaid": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 117500,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": false,
        "greaterThanZero": true,
        "displaySymbolValue": "117500 CFA"
      },
      "totalOutstanding": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 0,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0 CFA"
      },
      "totalInArrears": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 0,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0 CFA"
      },
      "totalWaived": {
        "currencyCode": "XOF",
        "currencyDigitsAfterDecimal": 0,
        "amount": 0,
        "defaultName": "CFA Franc BCEAO",
        "nameCode": "currency.XOF",
        "displaySymbol": "CFA",
        "zero": true,
        "greaterThanZero": false,
        "displaySymbolValue": "0 CFA"
      }
    },
    "loanRepayments": [
      {
        "id": 2,
        "date": "2009-11-13",
        "principal": {
          "currencyCode": "XOF",
          "currencyDigitsAfterDecimal": 0,
          "amount": 100000,
          "defaultName": "CFA Franc BCEAO",
          "nameCode": "currency.XOF",
          "displaySymbol": "CFA",
          "zero": false,
          "greaterThanZero": true,
          "displaySymbolValue": "100000 CFA"
        },
        "interest": {
          "currencyCode": "XOF",
          "currencyDigitsAfterDecimal": 0,
          "amount": 17500,
          "defaultName": "CFA Franc BCEAO",
          "nameCode": "currency.XOF",
          "displaySymbol": "CFA",
          "zero": false,
          "greaterThanZero": true,
          "displaySymbolValue": "17500 CFA"
        },
        "total": {
          "currencyCode": "XOF",
          "currencyDigitsAfterDecimal": 0,
          "amount": 117500,
          "defaultName": "CFA Franc BCEAO",
          "nameCode": "currency.XOF",
          "displaySymbol": "CFA",
          "zero": false,
          "greaterThanZero": true,
          "displaySymbolValue": "117500 CFA"
        },
        "totalWaived": null,
        "overpaid": null,
        "transactionOffsetFromToday": -921
      }
    ]
  },
  "arrearsTolerance": {
    "currencyCode": "XOF",
    "currencyDigitsAfterDecimal": 0,
    "amount": 1000,
    "defaultName": "CFA Franc BCEAO",
    "nameCode": "currency.XOF",
    "displaySymbol": "CFA",
    "zero": false,
    "greaterThanZero": true,
    "displaySymbolValue": "1000 CFA"
  },
  "waiveAllowed": false,
  "makeRepaymentAllowed": false,
  "rejectAllowed": false,
  "withdrawnByApplicantAllowed": false,
  "undoApprovalAllowed": false,
  "disbursalAllowed": false,
  "anyActionOnLoanAllowed": false,
  "maxSubmittedOnOffsetFromToday": -1233,
  "maxApprovedOnOffsetFromToday": -1230,
  "maxDisbursedOnOffsetFromToday": -1223,
  "actualLoanTermInDays": 302,
  "actualLoanTermInMonths": 9,
  "loanTermInDays": 304,
  "loanTermInMonths": 10
}

Create a New Loan/Submit a Loan Application

Arguments

command: String Optional, case-insensitive; The default action is to Submit a New Loan Application. If the value is 'calculateLoanSchedule' then a new loan entry is created without entering the loan life cycle.

POST https://thedomainname/api/v1/loans

https://localhost:8443/mifosng-provider/api/v1/loans
        
        
        Content-Type: application/json
        Request Body:
        new json here

{"entityId": 2}

Approve, Disburse, Reject a Loan or Withdraw a Loan Application

Arguments

command: String Mandatory? what happens if command wrong, , case-insensitive; 'approve' : Approve Loan; 'disburse' : Disburse Loan; 'reject' : Reject Loan; 'withdrewbyclient' : Client Withdrew Loan Application

POST https://thedomainname/api/v1/loans/{loanId}

https://localhost:8443/mifosng-provider/api/v1/loans/1?command=approve
                
                
                Content-Type: application/json
                Request Body:
                new json here

{
    "entityId": 2
}

Delete a Loan

DELETE https://thedomainname/api/v1/loans/{loanId}

https://localhost:8443/mifosng-provider/api/v1/loans/1
                
                
                Content-Type: application/json
                Request Body:
                new json here

{
    "entityId": 2
}

Undo Loan Approval/ Undo Loan Disbursal

command: String Mandatory? what happens if command wrong, , case-insensitive; 'undoapproval' : Undo Loan Approval; 'undodisbursal' : Undo Loan Disbursal

POST https://thedomainname/api/v1/loans/{loanId}/undo

https://localhost:8443/mifosng-provider/api/v1/loans/1/undo
                
                
                Content-Type: application/json
                Request Body:
                new json here

{
    "entityId": 2
}

Retrieve Loan Repayment/Loan Waiver Template

Returns a template to help with entering loan repayments and waivers.

Arguments

type: String Optional, case-insensitive; The default action is to return details for Repayment of a loan. If the value is 'waiver' then details relevant to Waiving a loan amount are returned.

Example Request: https://localhost:8443/mifosng-provider/api/v1/loans/1/transactions/template?type=waiver"

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

 to be done

Make a Repayment / Loan Waiver

type: String Optional, case-insensitive; The default action is to make a Loan Repayment. If the value is 'waiver' then a Loan Waiver is made.

POST https://thedomainname/api/v1/loans/{loanId}/transactions

https://localhost:8443/mifosng-provider/api/v1/loans/1/transactions
                
                
                Content-Type: application/json
                Request Body:
                new json here

{
    "entityId": 2
}

Retrieve a Repayment or Waiver Details

Example Request: https://localhost:8443/mifosng-provider/api/v1/loans/1/transactions/1

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

Adjust a Repayment or Waiver

PUT https://thedomainname/api/v1/loans/{loanId}/transactions/{transactionId}

https://localhost:8443/mifosng-provider/api/v1/loans/1/transactions/1
                
                
                Content-Type: application/json
                Request Body:
                new json here

{
    "entityId": 2
}

Offices

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

List Offices

Example Requests:

https://localhost:8443/mifosng-provider/api/v1/offices?pretty=true

https://localhost:8443/mifosng-provider/api/v1/offices?fields=id,name,openingDate&pretty=true

GET https://thedomainname/api/v1/offices

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

Retrieve Office Details Template

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

Field Defaults
Allowed Value Lists

Example Request:

https://localhost:8443/mifosng-provider/api/v1/offices/template?pretty=true

GET https://thedomainname/api/v1/offices/template

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

Retrieve an Office

Example Requests:

https://localhost:8443/mifosng-provider/api/v1/offices/1?pretty=true

https://localhost:8443/mifosng-provider/api/v1/offices/1?pretty=true&template=true

https://localhost:8443/mifosng-provider/api/v1/offices/1?pretty=true&fields=id,name,parentName

GET https://thedomainname/api/v1/offices/1

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

Create an Office

POST https://thedomainname/api/v1/offices

POST https://localhost:8443/mifosng-provider/api/v1/offices
Content-Type: application/json 
Request Body:
{
 "name": "Example New Branch", 
 "dateFormat": "dd MMMM yyyy", 
 "openingDateFormatted": "01 July 2007", 
 "parentId": 2 
}

{
  "entityId": 9
}

Update Office

Update office details.

Example Request: https://localhost:8443/mifosng-provider/api/v1/offices/1

PUT https://thedomainname/api/v1/offices/1

PUT https://localhost:8443/mifosng-provider/api/v1/offices/1
Content-Type: application/json
Request Body:
{
  "name": "Name is updated"
}

{
  "entityId": 1
}

Loan Products

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

List Loan Products

Example Request: https://localhost:8443/mifosng-provider/api/v1/loanproducts

GET https://thedomainname/api/v1/loanproducts

    {
    "products": [
    {
    "id": 1,
    "name": "Agricultural Loan",
    "description": "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
    "principalMoney": {
    "currencyCode": "XOF",
    "currencyDigitsAfterDecimal": 0,
    "amount": 100000,
    "defaultName": "CFA Franc BCEAO",
    "nameCode": "currency.XOF",
    "displaySymbol": "CFA",
    "zero": false,
    "greaterThanZero": true,
    "displaySymbolValue": "100000 CFA"
    },
    "interestRatePerPeriod": 1.75,
    "interestRatePeriod": 2,
    "annualInterestRate": 21,
    "interestMethod": 0,
    "interestRateCalculatedInPeriod": 0,
    "numberOfInterestFreePeriods": 0,
    "repaidEvery": 12,
    "repaymentPeriodFrequency": 2,
    "numberOfRepayments": 1,
    "amortizationMethod": 1,
    "inArrearsTolerance": {
    "currencyCode": "XOF",
    "currencyDigitsAfterDecimal": 0,
    "amount": 1000,
    "defaultName": "CFA Franc BCEAO",
    "nameCode": "currency.XOF",
    "displaySymbol": "CFA",
    "zero": false,
    "greaterThanZero": true,
    "displaySymbolValue": "1000 CFA"
    },
    "createdOn": "2012-04-12T00:00:00.000+10:00",
    "lastModifedOn": "2012-04-12T00:00:00.000+10:00",
    "possibleCurrencies": [],
    "possibleAmortizationOptions": [],
    "possibleInterestOptions": [],
    "possibleInterestRateCalculatedInPeriodOptions": [],
    "repaymentFrequencyOptions": [],
    "interestFrequencyOptions": [],
    "interestRebateAllowed": false,
    "flexible": false
    }
    ]
    }

Retrieve Loan Product Details Template

Returns a template that contains the loan product fields and allowed value lists. This helps build a maintenance User Interface.

Example Request: https://localhost:8443/mifosng-provider/api/v1/loanproducts/template

GET https://thedomainname/api/v1/loanproducts/template

{
"id": null,
"name": null,
"description": null,
"principalMoney": {
"currencyCode": "XOF",
"currencyDigitsAfterDecimal": 0,
"amount": 0,
"defaultName": "CFA Franc BCEAO",
"nameCode": "currency.XOF",
"displaySymbol": "CFA",
"zero": true,
"greaterThanZero": false,
"displaySymbolValue": "0 CFA"
},
"interestRatePerPeriod": 0,
"interestRatePeriod": 2,
"annualInterestRate": 0,
"interestMethod": 0,
"interestRateCalculatedInPeriod": 1,
"numberOfInterestFreePeriods": 0,
"repaidEvery": 1,
"repaymentPeriodFrequency": 2,
"numberOfRepayments": 0,
"amortizationMethod": 1,
"inArrearsTolerance": {
"currencyCode": "XOF",
"currencyDigitsAfterDecimal": 0,
"amount": 0,
"defaultName": "CFA Franc BCEAO",
"nameCode": "currency.XOF",
"displaySymbol": "CFA",
"zero": true,
"greaterThanZero": false,
"displaySymbolValue": "0 CFA"
},
"createdOn": null,
"lastModifedOn": null,
"possibleCurrencies": [
{
"code": "XOF",
"name": "CFA Franc BCEAO",
"decimalPlaces": 0,
"displaySymbol": "CFA",
"nameCode": "currency.XOF",
"displayLabel": "CFA Franc BCEAO (CFA)"
},
{
"code": "ETB",
"name": "Ethiopian Birr",
"decimalPlaces": 2,
"displaySymbol": null,
"nameCode": "currency.ETB",
"displayLabel": "Ethiopian Birr [ETB]"
}
],
"possibleAmortizationOptions": [
{
"id": 1,
"value": "Equal installments"
},
{
"id": 0,
"value": "Equal principle payments"
}
],
"possibleInterestOptions": [
{
"id": 0,
"value": "Declining Balance"
},
{
"id": 1,
"value": "Flat"
}
],
"possibleInterestRateCalculatedInPeriodOptions": [
{
"id": 0,
"value": "Daily"
},
{
"id": 1,
"value": "Same as repayment period"
}
],
"repaymentFrequencyOptions": [
{
"id": 0,
"value": "Days"
},
{
"id": 1,
"value": "Weeks"
},
{
"id": 2,
"value": "Months"
}
],
"interestFrequencyOptions": [
{
"id": 2,
"value": "Per month"
},
{
"id": 3,
"value": "Per year"
}
],
"interestRebateAllowed": false,
"flexible": false
}

Retrieve a Loan Product

Returns loan product fields. It also returns allowed value lists which help build a maintenance User Interface. JPW - includes validation values (might be ok or option), enum?

Example Request: https://localhost:8443/mifosng-provider/api/v1/loanproducts/1

GET https://thedomainname/api/v1/loanproducts/{productId}

{
"id": 1,
"name": "Agricultural Loan",
"description": "An agricultural loan given to farmers to help buy crop, stock and machinery. With an arrears tolerance setting of 1,000 CFA, loans are not marked as 'in arrears' or 'in bad standing' if the amount outstanding is less than this. Interest rate is described using monthly percentage rate (MPR) even though the loan typically lasts a year and requires one repayment (typically at time when farmer sells crop)",
"principalMoney": {
"currencyCode": "XOF",
"currencyDigitsAfterDecimal": 0,
"amount": 100000,
"defaultName": "CFA Franc BCEAO",
"nameCode": "currency.XOF",
"displaySymbol": "CFA",
"zero": false,
"greaterThanZero": true,
"displaySymbolValue": "100000 CFA"
},
"interestRatePerPeriod": 1.75,
"interestRatePeriod": 2,
"annualInterestRate": 21,
"interestMethod": 0,
"interestRateCalculatedInPeriod": 0,
"numberOfInterestFreePeriods": 0,
"repaidEvery": 12,
"repaymentPeriodFrequency": 2,
"numberOfRepayments": 1,
"amortizationMethod": 1,
"inArrearsTolerance": {
"currencyCode": "XOF",
"currencyDigitsAfterDecimal": 0,
"amount": 1000,
"defaultName": "CFA Franc BCEAO",
"nameCode": "currency.XOF",
"displaySymbol": "CFA",
"zero": false,
"greaterThanZero": true,
"displaySymbolValue": "1000 CFA"
},
"createdOn": "2012-04-12T00:00:00.000+10:00",
"lastModifedOn": "2012-04-12T00:00:00.000+10:00",
"possibleCurrencies": [
{
"code": "XOF",
"name": "CFA Franc BCEAO",
"decimalPlaces": 0,
"displaySymbol": "CFA",
"nameCode": "currency.XOF",
"displayLabel": "CFA Franc BCEAO (CFA)"
},
{
"code": "ETB",
"name": "Ethiopian Birr",
"decimalPlaces": 2,
"displaySymbol": null,
"nameCode": "currency.ETB",
"displayLabel": "Ethiopian Birr [ETB]"
}
],
"possibleAmortizationOptions": [
{
"id": 1,
"value": "Equal installments"
},
{
"id": 0,
"value": "Equal principle payments"
}
],
"possibleInterestOptions": [
{
"id": 0,
"value": "Declining Balance"
},
{
"id": 1,
"value": "Flat"
}
],
"possibleInterestRateCalculatedInPeriodOptions": [
{
"id": 0,
"value": "Daily"
},
{
"id": 1,
"value": "Same as repayment period"
}
],
"repaymentFrequencyOptions": [
{
"id": 0,
"value": "Days"
},
{
"id": 1,
"value": "Weeks"
},
{
"id": 2,
"value": "Months"
}
],
"interestFrequencyOptions": [
{
"id": 2,
"value": "Per month"
},
{
"id": 3,
"value": "Per year"
}
],
"interestRebateAllowed": false,
"flexible": false
}

Create a Loan Product

POST https://thedomainname/api/v1/loanproducts

https://localhost:8443/mifosng-provider/api/v1/loanproducts
Content-Type: application/json
Request Body:
{
  "name": "New kind of Loan",
  "description": "A description not exceeding 500 characters.",
  "currencyCode": "XOF",
  "digitsAfterDecimal": 0,
  "principal": 100000,
  "inArrearsToleranceAmount": 1000,
  "numberOfRepayments": 1,
  "repaymentEvery": 1,
  "repaymentFrequency": 2,
  "amortizationMethod": 1,
  "interestRatePerPeriod": 1.75,
  "interestRateFrequencyMethod": 2,
  "interestCalculationPeriodMethod": 1,
  "interestMethod": 0
}

Update a Loan Product

POST https://thedomainname/api/v1/loanproducts/{loanId}

https://localhost:8443/mifosng-provider/api/v1/loanproducts/1
Content-Type: application/json
Request Body:
{
  "name": "New kind of Loan updated",
  "description": "An updated description not exceeding 500 characters.",
  "currencyCode": "XOF",
  "digitsAfterDecimal": 0,
  "principal": 100000,
  "inArrearsToleranceAmount": 1000,
  "numberOfRepayments": 1,
  "repaymentEvery": 1,
  "repaymentFrequency": 2,
  "amortizationMethod": 1,
  "interestRatePerPeriod": 1.75,
  "interestRateFrequencyMethod": 2,
  "interestCalculationPeriodMethod": 1,
  "interestMethod": 0
}

Configuration

Application related configuration like being able to select 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:

https://localhost:8443/mifosng-provider/api/v1/configurations/currency?pretty=true

https://localhost:8443/mifosng-provider/api/v1/configurations/currency?pretty=true&fields=selectedCurrencyOptions

GET https://thedomainname/api/v1/configurations/currency

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

Update Currency Configuration

Updates the list of currencies permitted for use.

PUT https://thedomainname/api/v1/configurations/currency

PUT https://localhost:8443/mifosng-provider/api/v1/configurations/currency
Content-Type: application/json
Request Body:
{ 
 "currencies": ["USD", "GBP","XOF","ETB"]
}

Question Outstanding

Additional Fields

In Mifos X, any number of "Sets" of "Additional Fields" can be configured for a Mifos X database table ("Type").

For example, portfolio_client is the database table that holds client data. Typically, MFI's want more client related fields than is provided by Mifos X out-of-the-box. The MFI might add a Set called "Additional Info" containing some fields that are typically input when creating a client. They might then add another Set called "Highly Improbable Info" containing some fields that are only input in exceptional circumstances.

The additional fields resource allows you to retrieve and update any Additional Fields data that has been configured in Mifos X.

The Mifos X Individual Lending client application uses a JQuery plugin called stretchydata which, itself, uses this additional fields resource to provide a pretty flexible additional fields User Interface (UI). Put a link to an example here.

List Additional Fields Sets

Lists the Sets of additional fields have been defined in Mifos X.

Arguments

type: optional; The Additional Fields Type (Mifos X database table) to restrict the output to

Example Request: https://localhost:8443/mifosng-provider/api/v1/additionalfields?type=portfolio_client

GET https://thedomainname/api/v1/additionalfields

{
                "additionalFieldsSets": [
                {
                "id": 1,
                "name": "Additional Information",
                "type": "portfolio_client"
                },
                {
                "id": 9,
                "name": "Highly Improbable Info",
                "type": "portfolio_client"
                }
                ]
                }

Retrieve Additional Fields

Returns the Set of Additional Fields data for the ID provided. The ID is the id field of the Type table e.g. portfolio_client might have an id value of 4. The output is a JSON formatted "Generic Resultset". The Generic Resultset contains Column Heading as well as Data information. The Column Heading information may include allowed values (columnValues array).

Example Request: https://localhost:8443/mifosng-provider/api/v1/additionalfields/portfolio_client/Additional Information/2

GET https://thedomainname/api/v1/additionalfields/{type}/{set}/{id}

{
                "columnHeaders": [
                {
                "columnName": "Ethnic Group",
                "columnType": "String",
                "columnLength": 50,
                "columnDisplayType": "List",
                "columnValues": [
                "Bedouin",
                "Berber",
                "Italian",
                "Miknasa",
                "Mrazig",
                "Other",
                "Unknown"
                ]
                },
                {
                "columnName": "Ethnic Group Other",
                "columnType": "String",
                "columnLength": 50,
                "columnDisplayType": null,
                "columnValues": []
                },
                {
                "columnName": "Household Location",
                "columnType": "String",
                "columnLength": 50,
                "columnDisplayType": "List",
                "columnValues": [
                "East Sikkim",
                "North Sikkim",
                "South Sikkim",
                "West Sikkim",
                "Other"
                ]
                },
                {
                "columnName": "Household Location Other",
                "columnType": "String",
                "columnLength": 50,
                "columnDisplayType": null,
                "columnValues": []
                },
                {
                "columnName": "Religion",
                "columnType": "String",
                "columnLength": 50,
                "columnDisplayType": "List",
                "columnValues": [
                "Protestant",
                "Catholic",
                "Muslim",
                "Animist",
                "Atheist",
                "Other",
                "Unknown"
                ]
                },
                {
                "columnName": "Religion Other",
                "columnType": "String",
                "columnLength": 50,
                "columnDisplayType": null,
                "columnValues": []
                },
                {
                "columnName": "Knowledge of Person",
                "columnType": "String",
                "columnLength": 50,
                "columnDisplayType": "List",
                "columnValues": [
                "Staff member",
                "Spouse of staff member",
                "Son/daughter of staff member",
                "Friend of staff member",
                "Not known by any staff member",
                "Other"
                ]
                },
                {
                "columnName": "Gender",
                "columnType": "String",
                "columnLength": 10,
                "columnDisplayType": "List",
                "columnValues": [
                "Female",
                "Male"
                ]
                },
                {
                "columnName": "Whois",
                "columnType": "Text",
                "columnLength": 0,
                "columnDisplayType": null,
                "columnValues": []
                }
                ],
                "data": [
                {
                "row": [
                "Berber",
                null,
                "East Sikkim",
                null,
                "Animist",
                "jjjjjjj",
                "Son/daughter of staff member",
                "Female",
                "its\r\nme of\r\ncourse\r\nyes\r\nend and the end of it all"
                ]
                }
                ]
                }

Update Additional Fields

Updates (or creates) the Set of Additional Fields data for the ID provided. The ID is the id field of the Type table e.g. portfolio_client might have an id value of 4.

POST https://thedomainname/api/v1/additionalfields/{type}/{set}/{id}

https://localhost:8443/mifosng-provider/api/v1/additionalfields/portfolio_client/Additional Information/2
                
                
                Content-Type: application/json
                Request Body:
                {
                "Ethnic_Group":"Berber",
                "Ethnic_Group_Other":"",
                "Household_Location":"East Sikkim",
                "Household_Location_Other":"",
                "Religion":"Animist",
                "Religion_Other":"jjjjjjj",
                "Knowledge_of_Person":"Son/daughter of staff member",
                "Gender":"Female",
                "Whois":"its\r\nme of\r\ncourse\r\nyes\r\nend and the end of it all"
                }

{
                "entityId": 2
                }

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 URI.

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

Add examples showing links to client listing report producing json, then csv, then a pentaho report producing html, pdf, csv

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). Put a link to an example here.

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 Request: https://localhost:8443/mifosng-provider/api/v1/reports

GET https://thedomainname/api/v1/reports

{
                "columnHeaders": [
                {
                "columnName": "report_id",
                "columnType": "INT",
                "columnLength": null,
                "columnDisplayType": null,
                "columnValues": []
                },
                {
                "columnName": "report_name",
                "columnType": "VARCHAR",
                "columnLength": null,
                "columnDisplayType": null,
                "columnValues": []
                },
                {
                "columnName": "report_type",
                "columnType": "VARCHAR",
                "columnLength": null,
                "columnDisplayType": null,
                "columnValues": []
                },
                ... more "columnHeaders" entries
                ],
                "data": [
                {
                "row": [
                "29",
                "Client Listing",
                "Table",
                null,
                null,
                "5",
                null,
                "selectOfficeId"
                ]
                },
                {
                "row": [
                "42",
                "Client Listing - Additional and Unlikely",
                "Table",
                null,
                null,
                "5",
                null,
                "selectOfficeId"
                ]
                },
                {
                "row": [
                "30",
                "Client Loans Listing",
                "Table",
                null,
                null,
                "5",
                null,
                "selectOfficeId"
                ]
                },
                ... more "Row" entries
                ]
                }

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

Example Request: https://localhost:8443/mifosng-provider/api/v1/reports/Client%20Listing?R_officeId=1

GET https://thedomainname/api/v1/reports/{reportName}

{
                "columnHeaders": [
                {
                "columnName": "Office/Branch",
                "columnType": "VARCHAR",
                "columnLength": null,
                "columnDisplayType": null,
                "columnValues": []
                },
                {
                "columnName": "Name",
                "columnType": "VARCHAR",
                "columnLength": null,
                "columnDisplayType": null,
                "columnValues": []
                },
                {
                "columnName": "Joining Date",
                "columnType": "DATE",
                "columnLength": null,
                "columnDisplayType": null,
                "columnValues": []
                }
                ],
                "data": [
                {
                "row": [
                "Demo MFI Head Office",
                "O'Meara, Patrick",
                "2009-01-04"
                ]
                },
                {
                "row": [
                "Demo MFI Head Office",
                "O'Meara, Dennis",
                "2009-01-04"
                ]
                },
                {
                "row": [
                "Demo MFI Head Office",
                "Smith, John",
                "2009-01-11"
                ]
                },
                ... more "row" entries
                ]
                }

Authentication

An API capability to allowed client applications verify authentication details.

Verify authentication

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

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

POST https://localhost:8443/mifosng-provider/api/v1/authentication?username=super1&password=demo
Content-Type: application/json
No Request Body

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

Users

An API capability to support user administration.

Retrieve list of users

Example Requests:

https://localhost:8443/mifosng-provider/api/v1/users?pretty=true

https://localhost:8443/mifosng-provider/api/v1/users?pretty=true&fields=id,username,email,officeName

GET https://thedomainname/api/v1/users

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

Retrieve User Details Template

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

Field Defaults
Allowed Value Lists

Example Request:

https://localhost:8443/mifosng-provider/api/v1/users/template?pretty=true

GET https://thedomainname/api/v1/users/template

{
  "allowedOffices" : [ {
    "id" : 1,
    "name" : "change super user"
  } ],
  "availableRoles" : [ {
    "id" : 1,
    "name" : "Super user",
    "description" : "This role provides all application permissions.",
    "availablePermissions" : [ ],
    "selectedPermissions" : [ ]
  }, {
    "id" : 2,
    "name" : "Field officer",
    "description" : "A field officer role allows the user to add client and loans and view reports but nothing else.",
    "availablePermissions" : [ ],
    "selectedPermissions" : [ ]
  }...]
}

Retrieve a User

Example Requests:

https://localhost:8443/mifosng-provider/api/v1/users/1?pretty=true

https://localhost:8443/mifosng-provider/api/v1/users/1?pretty=true&template=true

https://localhost:8443/mifosng-provider/api/v1/users/1?pretty=true&fields=username,officeName

GET https://thedomainname/api/v1/users/1

{
  "id" : 1,
  "officeId" : 1,
  "officeName" : "change super user",
  "username" : "mifos",
  "firstname" : "App",
  "lastname" : "Administrator",
  "email" : "demomfi@mifos.org",
  "selectedRoles" : [ {
    "id" : 1,
    "name" : "Super user",
    "description" : "This role provides all application permissions.",
    "availablePermissions" : [ ],
    "selectedPermissions" : [ {
      "id" : 1,
      "name" : "User administration ALL",
      "description" : "An application user will have permission to execute all tasks related to user administration.",
      "code" : "USER_ADMINISTRATION_SUPER_USER_ROLE",
      "groupType" : 1
    }, {
      "id" : 4,
      "name" : "Reporting ALL",
      "description" : "An application user will have permission to execute and view all reports.",
      "code" : "REPORTING_SUPER_USER_ROLE",
      "groupType" : 4
    }...]
  } ]
}

Create new user

Adds new application user.

POST https://thedomainname/api/v1/users

POST https://localhost:8443/mifosng-provider/api/v1/users
Content-Type: application/json
Request body:
{ 
 "username": "Another New User zll", 
 "firstname": "Test", 
 "lastname": "User", 
 "password": "window75",
 "repeatPassword": "window75f",
 "email": "whatever@mifos.org", 
 "officeId": 1, 
 "roles": ["2","3"] 
}


{
  "entityId": 11
}

Update existing user

PUT https://thedomainname/api/v1/users/{userId)

PUT https://localhost:8443/mifosng-provider/api/v1/users/3
Content-Type: application/json
Request body:{ 
 "firstname": "Test",
 "roles": ["2"] 
}


{
  "entityId": 3
}

Delete a User

Removes the user and the associated roles and permissions.

DELETE https://thedomainname/api/v1/users/{userId}

DELETE https://localhost:8443/mifosng-provider/api/v1/users/20
Content-Type: application/json
No Request Body

Question outstanding

Roles

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

List Roles

Example Requests:

https://localhost:8443/mifosng-provider/api/v1/roles?pretty=true

https://localhost:8443/mifosng-provider/api/v1/roles?pretty=true&fields=name

GET https://thedomainname/api/v1/roles

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

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

https://localhost:8443/mifosng-provider/api/v1/roles/template?pretty=true

GET https://thedomainname/api/v1/roles/template

{
  "availablePermissions" : [ {
    "id" : 1,
    "name" : "User administration ALL",
    "description" : "An application user will have permission to execute all tasks related to user administration.",
    "code" : "USER_ADMINISTRATION_SUPER_USER_ROLE",
    "groupType" : 1
  }, {
    "id" : 2,
    "name" : "Organisation adminsitration ALL",
    "description" : "An application user will have permission to execute all tasks related to organisation administration.",
    "code" : "ORGANISATION_ADMINISTRATION_SUPER_USER_ROLE",
    "groupType" : 2
  }, {
    "id" : 3,
    "name" : "Portfolio management ALL",
    "description" : "An application user will have permission to execute all tasks related to portfolio management.",
    "code" : "PORTFOLIO_MANAGEMENT_SUPER_USER_ROLE",
    "groupType" : 3
  }...]
}

Retrieve a Role

Example Requests:

https://localhost:8443/mifosng-provider/api/v1/roles/1?pretty=true

https://localhost:8443/mifosng-provider/api/v1/roles/1?pretty=true&template=true

https://localhost:8443/mifosng-provider/api/v1/roles/1?pretty=true&fields=name,selectedPermissions

GET https://thedomainname/api/v1/roles/{roleId}

{
  "id" : 1,
  "name" : "Super user",
  "description" : "This role provides all application permissions.",
  "selectedPermissions" : [ {
    "id" : 1,
    "name" : "User administration ALL",
    "description" : "An application user will have permission to execute all tasks related to user administration.",
    "code" : "USER_ADMINISTRATION_SUPER_USER_ROLE",
    "groupType" : 1
  }, {
    "id" : 4,
    "name" : "Reporting ALL",
    "description" : "An application user will have permission to execute and view all reports.",
    "code" : "REPORTING_SUPER_USER_ROLE",
    "groupType" : 4
  }, {
    "id" : 3,
    "name" : "Portfolio management ALL",
    "description" : "An application user will have permission to execute all tasks related to portfolio management.",
    "code" : "PORTFOLIO_MANAGEMENT_SUPER_USER_ROLE",
    "groupType" : 3
  }, {
    "id" : 2,
    "name" : "Organisation adminsitration ALL",
    "description" : "An application user will have permission to execute all tasks related to organisation administration.",
    "code" : "ORGANISATION_ADMINISTRATION_SUPER_USER_ROLE",
    "groupType" : 2
  } ]
}

Create a New Role

POST https://thedomainname/api/v1/roles

POST https://localhost:8443/mifosng-provider/api/v1/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.", 
 "permissions": ["1", "2", "3"] 
}

{
  "entityId": 8
}

Update a Role

PUT https://thedomainname/api/v1/roles/{roleId}

PUT https://localhost:8443/mifosng-provider/api/v1/roles/8
Content-Type: application/json
Request body:
{ 
 "name": "Updated Role Name", 
 "permissions": ["1"] 
}

{
  "entityId": 8
}

Permissions

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

List Application Permissions

Example Requests:

https://localhost:8443/mifosng-provider/api/v1/permissions?pretty=true

https://localhost:8443/mifosng-provider/api/v1/permissions?pretty=true&fields=id,code

GET https://thedomainname/api/v1/permissions

[ {
  "id" : 1,
  "name" : "User administration ALL",
  "description" : "An application user will have permission to execute all tasks related to user administration.",
  "code" : "USER_ADMINISTRATION_SUPER_USER_ROLE",
  "groupType" : 1
}, {
  "id" : 2,
  "name" : "Organisation adminsitration ALL",
  "description" : "An application user will have permission to execute all tasks related to organisation administration.",
  "code" : "ORGANISATION_ADMINISTRATION_SUPER_USER_ROLE",
  "groupType" : 2
}, {
  "id" : 3,
  "name" : "Portfolio management ALL",
  "description" : "An application user will have permission to execute all tasks related to portfolio management.",
  "code" : "PORTFOLIO_MANAGEMENT_SUPER_USER_ROLE",
  "groupType" : 3
}...]

Overview

Core

Configuration

Additional Fields

Report

User Related

Convenience