Developer Center

Loans API

Last Updated: May 18, 2018 07:25AM CEST

URL

/api/loans/{ID}
/api/clients/{CLIENT_ID}/loans/{ID}
/api/groups/{GROUP_ID}/loans/{ID}
/api/loans/{ID}/custominformation/{customFieldId}
/api/loans/{ID}/templates/{templateId}
/api/loans/{ID}/settlementAccounts/{savingsId}
/api/loans/search 
/api/loans/{ID}/guarantees

Description

Allows you to retrieve and create/update new loan accounts for clients or groups. It's possible to look up loans by their state, by a branch or by a credit officer to which the loans are assigned to. Loans may be retrieved directly or from a client or group to which they belong. Actions that can be made to loan accounts:
Notice that the Loan Transactions API manages actions made on loans, such as the ones listed below:
  • approve loan account
  • disburse loan account
  • apply accrued interest
  • make repayment
  • apply fee
  • close loan account

Note

When retrieving templates, in order to get the template ID for a loan, use the Loan Products API. .

Methods

GET Loans

Allows retrieving loan accounts either directly by a their id or by looking up loans based on a filter.

Parameters

branchId The ID of the branch to which the loan accounts are assigned to
centreId The ID of the centre to which the loan accounts are assigned to
creditOfficerUsername The username of the credit officer to whom the loans are assigned to *
accountState The desired state of the accounts to filter on (APPROVED, ACTIVE, PARTIAL_APPLICATION, PENDING_APPROVAL, ACTIVE_IN_ARREARS, CLOSED_RESCHEDULED, CLOSED, CLOSED_WRITTEN_OFF, CLOSED_WITHDRAWN, CLOSED_REJECTED)
fullDetails Whether the full details of the loan account (such as custom fields or savings account settlement accounts) are retrieved. Boolean value ("true"/"false")."false" by default.
startDate Used when retrieving a specific document for loan accounts with transaction history from this date.
endDate Used when retrieving a specific document for loan accounts with transaction history up to this date.
fixedDaysOfMonth The day of the month when the repayment will be due. Optional.
* creditOfficerUsername is required if the user making the call has the"Credit Officer" role and the option"Can access other credit officers clients" is not activated.

Usage examples

//get a loan account by id
GET /api/loans/OHNP076

//get all the loans for a client with id 8
GET /api/clients/8/loans

//get all the loans for branch id 2 for credit officer 'tom' with accountstate 'APPROVED' (default pagination)
GET /api/loans?branchId=2&creditOfficerUsername=creditofficer&accountState=APPROVED

//get all the loans for centre id CD (default pagination)
GET /api/loans?centreId=CD

//same as above but paginated to a limit of 5
GET /api/loans?branchId=2&creditOfficerUsername=creditofficer&accountState=APPROVED&offset=0&limit=5

//get a specific document for a loan account
GET /api/loans/ABC9999/templates/402832b43809601c01380963a7b0033b

//get a specific document for loan account with transactions history
GET /api/loans/ABC9999/templates/402832b43809601c01380963a7b0033b?startDate=2015-01-01&endDate=2015-01-31

Samples responses

//full loan details of an active loan account
{
   "encodedKey":"402832b4380a2d8801380a9cac41000f",
   "id":"OHNP076",
   "accountHolderKey":"402832b43809601c013809639d6400e5",
   "accountHolderType":"CLIENT",
   "creationDate":"2012-06-20T17:57:16+0200",
   "approvedDate":"2012-06-28T11:03:28+0200",
   "lastModifiedDate":"2012-06-28T11:52:33+0200",
   "disbursementDate":"2012-06-28T00:00:00+0200",
   "lastAccountAppraisalDate":"2012-06-28T11:03:32+0200",
   "accountState":"ACTIVE",
   "productTypeKey":"402832b43809601c01380963a7b0033b",
   "loanName":"Agriculture Loan",
   "loanAmount":"950",
   "principalDue":"0",
   "principalPaid":"0",
   "principalBalance":"950",
   "interestDue":"0",
   "interestPaid":"0",
   "interestBalance":"0",
   "feesDue":"0",
   "feesPaid":"0",
   "penaltyDue":"0",
   "penaltyPaid":"0",
   "repaymentPeriodCount":1,
   "repaymentPeriodUnit":"MONTHS",
   "repaymentInstallments":5,
   "gracePeriod":0,
   "gracePeriodType":"NONE",
   "interestRate":"2.5",
   "interestChargeFrequency":"EVERY_FOUR_WEEKS",
   "interestCalculationMethod":"FLAT",
   "assignedBranchKey":"402832b43809601c01380963908b0009",
   "notes":"some_notes",
   "principalRepaymentInterval":1,
   "interestRateSource":"FIXED_INTEREST_RATE",
   "interestAdjustment":"0",
   "accruedInterest":"0",
   "arrearsTolerancePeriod":0,
   "customFieldValues":[
      {
         "encodedKey":"8ac91de9437b5b7b01437c938fac002a",
         "parentKey":"402832b43809601c013809639d6400e5",
         "customFieldKey":"8ac91de9430fd40201430fdc15a60361",
         "customField":{
            "encodedKey":"8ac91de9430fd40201430fdc15a60361",
            "id":"Special_Installements_Loan_Accou",
            "name":"Special Installements",
            "type":"LOAN_ACCOUNT_INFO",
            "dataType":"SELECTION",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "values":[
               "None",
               "One",
               "Ten"
            ],
            "amounts":{
               "Ten":"10",
               "None":"0",
               "One":"1"
            },
            "customFieldSet":{
               "encodedKey":"8ac91de9430fd40201430fdc15580350",
               "name":"Installments",
               "createdDate":"2013-12-20T11:55:18+0000",
               "indexInList":0,
               "type":"LOAN_ACCOUNT_INFO"
            },
            "indexInList":-1,
            "state":"NORMAL"
         },
         "value":"Ten",
         "amount":"10",
         "indexInList":-1,
         "customFieldID":"Special_Installements_Loan_Accou"
      },
      {
         "encodedKey":"8ac91de9437b5b7b01437c938fac002b",
         "parentKey":"402832b43809601c013809639d6400e5",
         "customFieldKey":"8ac91de9430fd40201430fdc15ae0363",
         "customField":{
            "encodedKey":"8ac91de9430fd40201430fdc15ae0363",
            "id":"Has_Many_Installements_Loan_Acco",
            "name":"Has Many Installements",
            "type":"LOAN_ACCOUNT_INFO",
            "dataType":"CHECKBOX",
            "valueLength":"SHORT",
            "isDefault":false,
            "isRequired":false,
            "customFieldSet":{
               "encodedKey":"8ac91de9430fd40201430fdc15580350",
               "name":"Installments",
               "createdDate":"2013-12-20T11:55:18+0000",
               "indexInList":0,
               "type":"LOAN_ACCOUNT_INFO"
            },
            "indexInList":-1,
            "state":"NORMAL"
         },
         "value":"TRUE",
         "indexInList":-1,
         "customFieldID":"Has_Many_Installements_Loan_Acco"
      }
   ],
   "settlementAccounts":[
      {
         "encodedKey":"402832b4380a2d8801380a380c9f0004",
         "id":"DAML394",
         "accountHolderKey":"402832b43809601c013809639e64011c",
         "accountHolderType":"CLIENT",
         "name":"Daily Savings",
         "creationDate":"2012-06-20T16:07:21+0200",
         "activationDate":"2012-06-20T14:07:34+0200",
         "lastModifiedDate":"2012-06-29T11:49:17+0200",
         "lastInterestCalculationDate":"2012-06-23T00:00:00+0200",
         "lastAccountAppraisalDate":"2012-06-23T11:02:43+0200",
         "productTypeKey":"402832b43809601c01380963a8de033d",
         "accountType":"REGULAR_SAVINGS",
         "accountState":"ACTIVE",
         "balance":"35",
         "accruedInterest":"4.5",
         "overdraftInterestAccrued":"0",
         "overdraftAmount":"0",
         "interestDue":"0",
         "feesDue":"0",
         "allowOverdraft":false,
         "notes":"Some notes",
         "interestPaymentPoint":"ON_ACCOUNT_MATURITY",
         "interestPaymentDates":[
            {
               "dayOfMonth":1,
               "monthOfYear":4,
               "year":0
            }
         ],
         "customFieldValues":[
            {
               "encodedKey":"8ac91de9437b5b7b01437c938fac002a",
               "parentKey":"402832b43809601c013809639d6400e5",
               "customFieldKey":"8ac91de9430fd40201430fdc15a60361",
               "customField":{
                  "encodedKey":"8ac91de9430fd40201430fdc15a60361",
                  "id":"INTEREST",
                  "name":"Interest",
                  "type":"SAVINGS_ACCOUNT_INFO",
                  "dataType":"SELECTION",
                  "valueLength":"SHORT",
                  "isDefault":false,
                  "isRequired":false,
                  "values":[
                     "None",
                     "One",
                     "Ten"
                  ],
                  "amounts":{
                     "Ten":"10",
                     "None":"0",
                     "One":"1"
                  },
                  "customFieldSet":{
                     "encodedKey":"8ac91de9430fd40201430fdc15580350",
                     "name":"Savings Account Info",
                     "createdDate":"2013-12-20T11:55:18+0000",
                     "indexInList":0,
                     "type":"SAVINGS_ACCOUNT_INFO"
                  },
                  "indexInList":-1,
                  "state":"NORMAL"
               },
               "value":"Ten",
               "amount":"10",
               "indexInList":-1,
               "customFieldID":"INTEREST"
            },
            {
               "encodedKey":"8ac91de9437b5b7b01437c938fac002b",
               "parentKey":"402832b43809601c013809639d6400e5",
               "customFieldKey":"8ac91de9430fd40201430fdc15ae0363",
               "customField":{
                  "encodedKey":"8ac91de9430fd40201430fdc15ae0363",
                  "id":"HAS_CHILDREN_INFO",
                  "name":"Is more than salary",
                  "type":"IS_MORE_THAN_SALARY",
                  "dataType":"CHECKBOX",
                  "valueLength":"SHORT",
                  "isDefault":false,
                  "isRequired":false,
                  "customFieldSet":{
                     "encodedKey":"8ac91de9430fd40201430fdc15580350",
                     "name":"Savings account info",
                     "createdDate":"2013-12-20T11:55:18+0000",
                     "indexInList":0,
                     "type":"SAVINGS_ACCOUNT_INFO"
                  },
                  "indexInList":-1,
                  "state":"NORMAL"
               },
               "value":"TRUE",
               "indexInList":-1,
               "customFieldID":"IS_MORE_THAN_SALARY"
            }
         ]
      }
   ],
   "disbursementDetails":{
      "expectedDisbursementDate":"2016-01-08",
      "firstRepaymentDate":"2016-02-08",
      "transactionDetails":{
         "transactionChannel":{
            "id":"RECEIPT",
            "encodedKey":"8a8080855281ef57015281ef9bc20436"
         }
      },
      "fees":[
         {
            "fee":{
               "encodedKey":"8a8080855283305201528369d0d3001c"
            }
         },
         {
            "fee":{
               "encodedKey":"8a8080855283305201528369d0d3001b"
            },
            "amount":"10"
         },
         {
            "fee":{
               "encodedKey":"8a808085528330520152836c5950002a"
            },
            "amount":"55"
         }
      ]
   }
}

POST Loans

Create basic loan accounts for individual clients and update the custom field values. The loan account details must be connected to a specific active product. For JSON Post if the identifier or encoded key will be provided an update will be executed(for now only the custom fields can be updated via JSON).

See Custom Fields API for more information about custom fields and custom fields sets.

Parameters for URL-Encoded calls

Using URL-Encoded calls basic loan accounts can be created. No updates are allowed using this approach (See JSON calls for update).
clientID ID of the client to create the loan for. Required.
productID ID of the product to use as the basis for this account. Required.
loanAmount How much to lend, must be within the product range. Required.
interestRate The interest rate for the loan account. Must be within the product range. Required.
installments The number of installments for this loan. The unit (e.g. days) is defined at the product level or can be set via the repaymentInterval parameter. Required.
interestSpread Interest to be added to active organisation index interest rate in order to find out actual interest rate. Required when the loan has an index interest rate.
repaymentPeriodCount Repayment period count (e.g. if repaymentInterval is set to MONTHS and repaymentPeriodCount is set to 1, repayments are expected every month). Required only if"Repayments Are Made Every" not defined in the product.
repaymentInterval The repayment interval type (possible values: DAYS, WEEKS, MONTHS, YEARS). Required only if "Repayments Are Made Every" not defined in the product.
gracePeriod The length of the grace period (in instalments) if applicable for the product
firstRepaymentDate The date of the expected first repayment (e.g. 2017-09-30)
anticipatedDisbursementDate The date of the anticipated disbursement date (e.g. 2018-08-09)
accountState Based on the product settings the account state will be set automatically to PENDING_APPROVAL or PARTIAL_APPLICATION states.
notes Any additional rich text html notes about the loan

URL-Encoded calls usage example

//creates a basic $1000 loan at 10% interest using the AGRL loan product for client 67
POST"productID=AGRL&loanAmount=1000&interestRate=10&installments=5¬es=hello" /api/clients/67/loans/

Parameters for JSON calls

Create and update loan accounts for individual clients. The loan account details must be connected to a specific active product. If the encoded key will be provided an update will be executed. For now only the guarantees(at a different endpoint) and the custom fields can be updated.

Note

Loan accounts can be created/update only for "Individual" and "Pure Group" Loan Product Types (Solidarity Group type is not supported for now).
encodedKey EncodedKey of the loan account to update.
id ID of the loan account.
accountHolderKey Encoded key of the account holder. Required.
accountHolderType The account holder type.(CLIENT/GROUP). Required.
productTypeKey Encoded key of the product to use as the basis for this account. Required.
loanAmount How much to lend, must be within the product range. Required.
interestRate The interest rate for the loan account. Must be within the product range. Required.
interestSpread Interest to be added to active organisation index interest rate in order to find out actual interest rate. Required when the loan has an index interest rate..
repaymentInstallments The number of installments for this loan. The unit (e.g. days) can be defined at the product level or via the repaymentInterval parameter. Required.
loanName The display loan name.
accountState Based on the product settings the account state will be set automatically to PENDING_APPROVAL or PARTIAL_APPLICATION states.
repaymentPeriodCount Repayment period count (e.g. if repaymentInterval is set to MONTHS and repaymentPeriodCount is set to 1, repayments are expected every month). Required only if "Repayments Are Made Every" not defined in the product.
repaymentPeriodUnit The repayment interval type (possible values: DAYS, WEEKS, MONTHS, YEARS). Required only if "Repayments Are Made Every" not defined in the product.
graceLength The length of the grace period (in installments) if applicable for the product
arrearsTolerancePeriod The arrears tolerance period (in days). Required only if product doesn't have a default arrears tolerance period defined.
assignedBranchKey The branch key on which the account is assigned to
assignedCentreKey The centre key on which the account is assigned to
firstRepaymentDate The date of the expected first repayment (e.g. 2017-09-30)
anticipatedDisbursementDate The date of the anticipated disbursement date (e.g. 2018-08-09)
notes Any additional rich text html notes about the loan
guarantees Compound of an array of:
  • guarantorKey: String, uuid encoded key of the guarantor.
  • amount: Number, the amount guaranteed
  • guarantorType: String, one of GUARANTOR, ASSET
  • customFieldvalues: An array containing"value","customfFieldID" as defined by the product.
funds Compound of an array of:
  • guarantorKey: String, uuid encoded key of the guarantor.
  • savingsAccountKey: String, uuid encoded key of the savings account
  • amount: The money that is lend from the savings account
  • interestCommission: Number, should be provided only if product has funderInterestCommissionAllocationType = FIXED_INTEREST_COMMISSIONS, it must be in product constraints.
disbursementDetails Define the disbursement rules such as amount, channel and fees before.
expectedDisbursementDate The date of the expected disbursement.
firstRepaymentDate The date of the expected first repayment (e.g. 2017-09-30)
transactionDetails The transaction details that will contain the transaction channel and the channel fields(bankNumber, etc) that will be converted to custom info. Provided fields must be available for the given channel.
fees The expected predefined fees that will be applied on the disbursement.
customInformation Custom fields to be added for disbursement details object. Provided fields must be available for the given channel and required validation is done based on field settings.
principalPaymentSettings Define the settings for Revolving Credit principal payments. Must be NULL or unspecified for other account types. If principal payment settings are not provided, then the product principal payment settings will be used by default
principalPaymentMethod The principal payment method, with two options: 'Flat Amount Principal Payment' Method and '% of Outstanding Principal Payment' Method. If provided, it should be the same as the principal payment method from the loan product.
amount Number. It can be specified only for Flat Amount Principal Payment Method.
percentage Number. It can be specified only for % of Outstanding Principal Payment Method.
principalCeilingValue Number. It can be specified only for % of Outstanding Principal Payment Method. If provided, it should be the same as the principal payment method from the loan product.
principalFloorValue Number. It can be specified only for % of Outstanding Principal Payment Method. If provided, it should be the same as the principal payment method from the loan product.
includeInterestInFloorAmount Check box. It can be specified only for % of Outstanding Principal Payment Method. If provided, it should be the same as the principal payment method from the loan product.
tranches Define disbursed amounts and the disbursed dates for tranched loans
amount Number. The amount of the tranche
expectedDisbursementDate The date of the expected tranche disbursement.

Parameters for Custom Fields

customFieldID The custom field Id. Required.
value The custom field Value. Required.

Custom Fields update notes

  • if for update the"customInformation":[] will not be provided the custom fields will not be updated
  • in order to remove all custom fields, an empty array for them must be provided (example: {loanAccount: {encodedKey:"abc", //other client information},"customInformation": []}
  • in order to remove custom fields from database, the information that will not be provided in the arrays
    • example: 3 custom fields in database, only one provided in the"customInformation" array for update, the other 2 from the database will get deleted and the one from the array will get stored/updated
    • the matching to determine the difference between an updated and a new field is done using customFieldID
    • if the custom field ID is invalid or the value is invalid an exception code will be returned
  • all used custom fields must be previously created in order to be used (for 'Field Type': 'Loans' in Administration), otherwise an exception code will be returned

Usage

//POST create a simple loan account with custom fields using JSON
{
  "loanAccount":{
     "accountHolderKey":"40288a1341273dad01412add591b039f",
     "productTypeKey":"40288a13437b71d201437b87af7d033f",
     "accountHolderType":"CLIENT",
     "loanAmount":"950",
     "repaymentInstallments":5,
     "interestRate":"2.5"
   },
  "customInformation":[
      {
        "value":"None",
        "customFieldID":"Special_Installements_Loan_Accou"
      },
      {
        "value":"2",
        "customFieldID":"Family_Members_Loan_Accounts"
      }
   ]
}
//POST create a loan account with many parameters and custom fields using JSON. All parameters must be applicable for the product
{
   "loanAccount":{
      "id":"Custom_ID",
      "accountHolderKey":"40288a13437b71d201437b87aa6300e1",
      "accountHolderType":"CLIENT",
      "creationDate":"2014-01-13T15:00:11+0200",
      "lastModifiedDate":"2014-01-13T15:00:11+0200",
      "accountState":"PENDING_APPROVAL",
      "productTypeKey":"40288a13437b71d201437b87af7d033f",
      "loanName":"Agriculture Loan",
      "loanAmount":"950",
      "principalDue":"0",
      "principalPaid":"0",
      "principalBalance":"0",
      "interestDue":"0",
      "interestPaid":"0",
      "interestBalance":"0",
      "feesDue":"0",
      "feesPaid":"0",
      "feesBalance":"0",
      "penaltyDue":"0",
      "penaltyPaid":"0",
      "penaltyBalance":"0",
      "scheduleDueDatesMethod":"INTERVAL",
      "repaymentPeriodCount":1,
      "repaymentPeriodUnit":"MONTHS",
      "repaymentInstallments":5,
      "gracePeriod":0,
      "gracePeriodType":"NONE",
      "interestRate":"2.5",
      "interestChargeFrequency":"EVERY_FOUR_WEEKS",
      "interestCalculationMethod":"DECLINING_BALANCE",
      "repaymentScheduleMethod":"FIXED",
      "paymentMethod":"HORIZONTAL",
      "interestApplicationMethod":"ON_DISBURSEMENT",
      "notes":"some_notes",
      "principalRepaymentInterval":1,
      "interestRateSource":"FIXED_INTEREST_RATE",
      "interestAdjustment":"0",
      "accruedInterest":"0",
      "arrearsTolerancePeriod":10,
      "guarantees":[
         {
            "guarantorKey":"8a80806852f38c860152f38de0ad0019",
            "amount":"950",
            "guarantorType":"GUARANTOR",
            "customFieldValues":[
               {
                  "CustomFieldID":"Employement_status",
                  "value":"Self-employed"
               }
            ]
         }
      ],
      "funds":[
         {
            "guarantorKey":"GUARANTOR_KEY",
            "savingsAccountKey":"SAVINGS_ACC_KEY",
            "amount":"500",
            "interestCommission":"4"
         }
      ]
   },
   "disbursementDetails":{
      "expectedDisbursementDate":"2016-01-08",
      "firstRepaymentDate":"2016-02-08",
      "transactionDetails":{
         "transactionChannel":{
            "id":"RECEIPT",
            "encodedKey":"8a8080855281ef57015281ef9bc20436"
         },
         "receiptNumber":"1146",
         "bankNumber":"bank1146"
      },
      "fees":[
         {
            "fee":{
               "encodedKey":"8a8080855283305201528369d0d3001c"
            }
         },
         {
            "fee":{
               "encodedKey":"8a8080855283305201528369d0d3001b"
            },
            "amount":"10"
         },
         {
            "fee":{
               "encodedKey":"8a808085528330520152836c5950002a"
            },
            "amount":"55"
         }
      ]
   },
   "customInformation":[
      {
         "value":"None",
         "customFieldID":"Special_Installements_Loan_Accounts"
      },
      {
         "value":"2",
         "customFieldID":"Family_Members_Loan_Accounts"
      }
   ]
}

//POST update a loan account custom fields with minimal parameters using JSON. All other provided parameters will be ignored for now.
POST api/loans/40288a13438b032a01438bee5bc300f0
{
  "loanAccount":{
     "productTypeKey":"40288a13437b71d201437b87af7d033f"
   },
  "customInformation":[
      {
        "value":"TEN",
        "customFieldID":"Special_Installements_Loan_Accounts"
      },
      {
        "value":"5",
        "customFieldID":"Family_Members_Loan_Accounts"
      }
   ]
}

//POST update custom fields using many loan account parameters. All loan account parameters, except the encoded key , will be ignored.
POST api/loans/40288a13438b032a01438bee5bc300f0
{
  "loanAccount":{
     "id":"Custom_ID",
     "accountHolderKey":"40288a13437b71d201437b87aa6300e1",
     "accountHolderType":"CLIENT",
     "creationDate":"2014-01-13T15:00:11+0200",
     "lastModifiedDate":"2014-01-13T15:00:11+0200",
     "accountState":"PENDING_APPROVAL",
     "productTypeKey":"40288a13437b71d201437b87af7d033f",
     "loanName":"Agriculture Loan",
     "loanAmount":"950",
     "principalDue":"0",
     "principalPaid":"0",
     "principalBalance":"0",
     "interestDue":"0",
     "interestPaid":"0",
     "interestBalance":"0",
     "feesDue":"0",
     "feesPaid":"0",
     "feesBalance":"0",
     "penaltyDue":"0",
     "penaltyPaid":"0",
     "penaltyBalance":"0",
     "scheduleDueDatesMethod":"INTERVAL",
     "repaymentPeriodCount":1,
     "repaymentPeriodUnit":"MONTHS",
     "repaymentInstallments":5,
     "gracePeriod":0,
     "gracePeriodType":"NONE",
     "interestRate":"2.5",
     "interestChargeFrequency":"EVERY_FOUR_WEEKS",
     "interestCalculationMethod":"DECLINING_BALANCE",
     "repaymentScheduleMethod":"FIXED",
     "paymentMethod":"HORIZONTAL",
     "interestApplicationMethod":"ON_DISBURSEMENT",
     "notes":"some_notes",
     "principalRepaymentInterval":1,
     "interestRateSource":"FIXED_INTEREST_RATE",
     "interestAdjustment":"0",
     "accruedInterest":"0",
     "arrearsTolerancePeriod":0
   },
  "customInformation":[
      {
        "value":"None",
        "customFieldID":"Special_Installements_Loan_Accounts"
      },
      {
        "value":"2",
        "customFieldID":"Family_Members_Loan_Accounts"
      }
   ]
}
//POST create a loan account with custom fields for disbursement details using JSON. All parameters must be applicable for the product
{  
   "loanAccount":{  
      "id":"Custom_ID",
      "accountHolderKey":"40288a13437b71d201437b87aa6300e1",
      "accountHolderType":"CLIENT",
      "creationDate":"2014-01-13T15:00:11+0200",
      "lastModifiedDate":"2014-01-13T15:00:11+0200",
      "accountState":"PENDING_APPROVAL",
      "productTypeKey":"40288a13437b71d201437b87af7d033f",
      "loanName":"Agriculture Loan",
      "loanAmount":"950",
      "principalDue":"0",
      "principalPaid":"0",
      "principalBalance":"0",
      "interestDue":"0",
      "interestPaid":"0",
      "interestBalance":"0",
      "feesDue":"0",
      "feesPaid":"0",
      "feesBalance":"0",
      "penaltyDue":"0",
      "penaltyPaid":"0",
      "penaltyBalance":"0",
      "scheduleDueDatesMethod":"INTERVAL",
      "repaymentPeriodCount":1,
      "repaymentPeriodUnit":"MONTHS",
      "repaymentInstallments":5,
      "gracePeriod":0,
      "gracePeriodType":"NONE",
      "interestRate":"2.5",
      "interestChargeFrequency":"EVERY_FOUR_WEEKS",
      "interestCalculationMethod":"DECLINING_BALANCE",
      "repaymentScheduleMethod":"FIXED",
      "paymentMethod":"HORIZONTAL",
      "interestApplicationMethod":"ON_DISBURSEMENT",
      "notes":"some_notes",
      "principalRepaymentInterval":1,
      "interestRateSource":"FIXED_INTEREST_RATE",
      "interestAdjustment":"0",
      "accruedInterest":"0",
      "arrearsTolerancePeriod":1
   },
   "disbursementDetails":{  
      "expectedDisbursementDate":"2016-01-08",
      "firstRepaymentDate":"2016-02-08",
      "transactionDetails":{  
         "transactionChannel":{  
            "id":"RECEIPT",
            "encodedKey":"8a8080855281ef57015281ef9bc20436"
         },
         "receiptNumber":"1146",
         "bankNumber":"bank1146"
      },
      "customInformation":[  
         {  
            "value":"None",
            "customFieldID":"Special_Installements_Loan_Accounts"
         },
         {  
            "value":"2",
            "customFieldID":"Family_Members_Loan_Accounts"
         }
      ]
   }
}

//POST create a revolving credit loan account using JSON, with principal payment settings having '% of Outstanding Principal' method.
{
	"loanAccount": {
		"id": "Custom_ID",
		"loanName":"Revolving Credit loan",
		"accountHolderType": "CLIENT",
		"accountHolderKey": "402880ed560343ca015603460fd400f6",
		"creationDate": "2016-01-01",
		"approvedDate": "2016-01-10",
		"accountState": "PENDING_APPROVAL",
		"firstRepaymentDate": "2016-02-08",
		"productTypeKey": "402880ed5603e34c015603e42b560001",
		"loanAmount": "1000",
		"interestRate":"5.5",
		"fixedDaysOfMonth" : ["1"],
		"customInformation":[],
		"arrearsTolerancePeriod" : "0",
		"notes": "custom notes",
		"principalPaymentSettings":{
			"principalPaymentMethod":"OUTSTANDING_PRINCIPAL_PERCENTAGE", 
			"principalCeilingValue":"20", 
			"principalFloorValue":"10", 
			"percentage" : "35", 
			"includeInterestInFloorAmount": "true"
		}
	}
}

//POST create a revolving credit loan account using JSON, with principal payment settings having 'Flat amount' method.
{
	"loanAccount": {
		"id": "Custom_ID",
		"loanName":"Revolving Credit loan",
		"accountHolderType": "CLIENT",
		"accountHolderKey": "402880ed560343ca015603460fd400f6",
		"creationDate": "2016-01-01",
		"approvedDate": "2016-01-10",
		"accountState": "PENDING_APPROVAL",
		"firstRepaymentDate": "2016-02-08",
		"productTypeKey": "402880ed5603e34c015603e42b560001",
		"loanAmount": "1000",
		"interestRate":"5.5",
		"fixedDaysOfMonth" : ["1"],
		"customInformation":[],
		"arrearsTolerancePeriod" : "0",
		"notes": "custom notes",
		"principalPaymentSettings":{
			"principalPaymentMethod":"FLAT", 
			"amount" : "35"
		}
	}
}

//POST create a tranched Loan Account
POST /api/loans 
{
   "loanAccount":{
      "accountHolderKey":"8a85863c5c626003015c62c6ec74cfad",
      "accountHolderType":"GROUP",
      "productTypeKey":"8a858e115af6c526015af720e7fdaaaa",
      "loanAmount":45000,
      "repaymentPeriodUnit":"MONTHS",
      "repaymentPeriodCount":1,
      "repaymentInstallments":15,
      "principalRepaymentInterval":1,
       "interestRate":10
      "tranches":[
         {
            "amount":15000,
            "expectedDisbursementDate":"2015-07-01T00:00:00+0000"
         },
         {
            "amount":30000,
            "expectedDisbursementDate":"2017-08-13T00:00:00+0000"
         }
      ]     
   }
}


//POST add a tranche for a created tranched Loan Account
POST api/loans/ABC123/tranches 
{
   "tranches":[
      {
         "amount":"400",
         "expectedDisbursementDate":"2015-07-01T00:00:00+0000"
      }
   ]
}


//POST edit a tranche for a created tranched Loan Account
POST api/loans/ABC123/tranches 
{
   "tranches":[
      {
         "encodedKey":"40288a134f219912014f21991d8c0004",
         "amount":"400",
         "expectedDisbursementDate":"2015-07-01T00:00:00+0000"
      }
   ]
}

//POST delete all tranche for a created tranched Loan Account
POST api/loans/ABC123/tranches 
{
   "tranches":[
   ]
}

Response

A 201 Response is returned if the loans was successfully created. The response Location header is set to the loan id and the created loan object is also returned.

Guarantees update

  • if for update the"guarantees":[] will not be provided the gurantees will not be updated
  • in order to remove all guarantees, an empty array for them must be provided (example: {loanAccount: {encodedKey:"abc", //other client information},"guarantees": []}
  • in order to remove guarantees from database, the information that will not be provided in the arrays
    • example: 3 guarantees in database, only one provided in the"guarantees" array for update, the other 2 from the database will get deleted and the one from the array will get stored/updated
    • the matching to determine the difference between an updated and a new field is done using guarantee enecoded key
    • if the guarantee encoded key is invalid or a field from the guarantee is invalid an exception code will be returned
  • for the update of custom fields of a guarantee the custom field update rules apply
  • the guarantees that have encodedKey are marked to be edited (if changed). Otherwise, if encodedKey is missing, we'll consider that a new security is added
  • guarantees can be added only if the product allows guarantees
  • the type for an existing security can't be changed
  • guarantees can be edited only for accounts that are not closed
//POST update a loan account guarantees using account encodedkey.
POST api/loans/40288a13438b032a01438bee5bc300f0/guarantees
{
   "guarantees":[
      {
         "encodedKey":"40288a5d4f3fbac9014f3fd02745001d",
         "guarantorType":"GUARANTOR",
         "amount":"50",
         "customFieldValues":[
            {
               "value":"Single",
               "customFieldID":"Marital_status"
            }
         ]
      },
      {
         "type":"ASSET",
         "amount":"100",
         "assetName":"Car"
      }
   ]
}
//POST add a loan account guarantee using account id.
POST api/loans/40288a13438b032a01438bee5bc300f0/guarantees
{
   "guarantees":[
      {
         "assetName":"cow2",
         "amount":"444",
         "guarantorType":"ASSET",
         "customFieldValues":[
            {
               "value":"Car",
               "customFieldID":"Type_Assets"
            },
            {
               "value":"Text",
               "customFieldID":"Bank_Account_Guarantors"
            }
         ]
      }
   ]
}

DELETE loan account

Allows the deletion of loan accounts based attachment id/encoded key

Usage example

//delete loan account using url-encoded call(id is used for account identification)
DELETE /api/loans/67

//delete  loan account with encoded key 8aa0f78f444f763601444f7fb89e0001
DELETE /api/loans/8aa0f78f444f763601444f7fb89e0001

Response

A success return code will be returned when the deletion is successful.
{
  "returnCode":0,
  "returnStatus":"SUCCESS"
}

PATCH Loan

Core loan fields can updated using the PATCH method. Normal validations and constraints as required in the POST method will be applied. All values passed to edit the account have to be within minimum and maximum constraints of the product.

Parameters for PATCH method for loan

loanAmount Number. It does not accept NULL.
interestRate Number. It cannot be edited for Index Interest Rates. It does not accept a NULL value if if the account uses a Fixed Interest Rate.
interestSpread Number. It cannot be edited for Fixed Interest Rate. It does not accept a NULL value if the account uses an Index Interest Rate.
repaymentInstallments Number. It does not accept NULL values.
repaymentPeriodCount Number. It does not accept NULL values.
repaymentPeriodUnit If a unit is specified in the product, the account must use the same. It does not accept NULL values.
expectedDisbursementDate Date. It does accept NULL.
firstRepaymentDate Date. Must be after the expected disbursement date.
gracePeriod Number. It does not accept NULL values if the product uses"Pay Interest Only" or"Forgiveness".
principalRepaymentInterval Number. It does not accept NULL values.
penaltyRate Number. It does not accept NULL values if the account has penalties enabled.
arrearsTolerancePeriod Number. It does not accept NULL values and the value should meet the product constraints for arrears tolerance period.
periodicPayment Number. It does not accept NULL values if the account uses balloon payments.
principalPaymentSettings Define the settings for Revolving Credit principal payments. Must be NULL or unspecified for other account types
amount Number. It can be edited for Flat Amount Principal Payment Method. It cannot be edited for % of Outstanding Principal Payment Method.
percentage Number. It can be edited for % of Outstanding Principal Payment Method. It cannot be edited for Flat Amount Principal Payment Method.

Usage Example

// Update the loan account VSA2006 with a new loan amount of 1000 and change the number of repayments to 10.
PATCH /api/loans/VSA2006
'{
  "loanAccount":
      {
        "loanAmount":"1000",
        "repaymentPeriodCount":"10"
      }
}'

PATCH Flat Amount or Percentage for Revolving Credit accounts

// Update the loan account VSA2006 with a new loan amount of 1000 and with a new principal payment amount of 400.
PATCH /api/loans/VSA2006
'{
  "loanAccount":
      {
        "loanAmount":"1000",
        "principalPaymentSettings":{
     	    "amount":"400"
      	}
      }
}'
// Update the loan account VSA2006 with a new loan amount of 1000 and with a new principal payment percentage of 22.
PATCH /api/loans/VSA2006
'{
  "loanAccount":
      {
        "loanAmount":"1000",
        "principalPaymentSettings":{
      	   "percentage":"22"
      	}
      }

Response

A 200 Response will be issued in case of a successful update. Otherwise an error code will be returned.

PATCH Loan Custom Field Values

Custom field values for a loan can be added/edited using PATCH method. The new custom field value is validated based on the custom field type defined in the Custom Field.

Parameters for PATCH custom fields method for loan

value New value for custom field. Required.
customFieldID The id of the custom field to be edited. Required when editing multiple.
customFieldSetGroupIndex The index of the custom field set to be edited. If it isn't provided, a new set is added.

Usage Example

// Update the custom field value to"10" based on the loan id(abc123) and on the custom field id(family_members)
PATCH '{"value":"10" }' /api/loans/abc123/custominformation/family_members

// Update the custom field value to"2012-10-10" based on the loan key(40288a134887e7e9014887f0eb720003) and on the custom field key(8a27a878491d417601491d48203100d9)
PATCH '{"value":"2012-10-10" }' /api/loans/40288a134887e7e9014887f0eb720003/custominformation/8a27a878491d417601491d48203100d9

// Update(add / edit) multiple grouped and / or standard fields from different groups for the loan account with the id 1111. 
// For a grouped custom field, if customFieldSetGroupIndex is present, 
// value is updated, if is missing, a new group is created. 
PATCH '{
  "customInformation": [
    {
      "customFieldID" : "IBAN",
      "value" : "DE123456789121243546783"
    },
    {
      "customFieldID" : "BIC",
      "value" : "1234566441",
      "customFieldSetGroupIndex" : "0"
    },
    {
      "customFieldID" : "BANK_ACCOUNT_TYPE",
      "value" : "Current Account",
      "customFieldSetGroupIndex" : "1"
    }
  ]
}' /api/loans/1111/custominformation/

Response

A 200 Response is returned if the loan custom field value was successfully created/updated.

GET Loan Custom Field Values

Allows retrieving a custom field value for a given loan account directly by the ID/key of the account and the ID/key of the custom field.

Usage Example

//get the custom field value of the custom field with the ID "family_members" for the loan account having ID "abc123"
GET /api/loans/abc123/custominformation/family_members
//get the custom field value of the custom field with the encoded key "8a8080a254a98efe0154a99ad86f00ef" for the loan account having key "8a8080a254a98efe0154a99ad8c400f6"
GET /api/loans/8a8080a254a98efe0154a99ad8c400f6/custominformation/8a8080a254a98efe0154a99ad86f00ef

Response

//response for a single custom field
[
  {
    "encodedKey": "8a8080a254a98efe0154a99ad9d301be",
    "parentKey": "8a8080a254a98efe0154a99ad8c400f6",
    "customFieldKey": "8a8080a254a98efe0154a99ad86f00ef",
    "customField": {
      "encodedKey": "8a8080a254a98efe0154a99ad86f00ef",
      "id": "Position_Clients",
      "creationDate": "2016-05-18T14:39:13+0000",
      "lastModifiedDate": "2016-05-18T14:40:19+0000",
      "name": "Position",
      "type": "LOAN_ACCOUNT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254a98efe0154a99ad84200ee",
        "name": "Custom Fields",
        "createdDate": "2016-05-13T10:12:58+0000",
        "indexInList": 0,
        "type": "LOAN_ACCOUNT_INFO",
        "usage": "SINGLE"
      },
      "indexInList": 3,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254a98efe0154a99ad87200f0",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254a98efe0154a99ad87300f1",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "Promotions manager",
    "indexInList": 0,
    "customFieldID": "Position_Clients",
    "customFieldSetGroupIndex": -1
  }
]
//response for a grouped custom field
[
  {
    "encodedKey": "8a8080a254c4397d0154c450f88d0034",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "LOAN_ACCOUNT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "LOAN_ACCOUNT_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "111",
    "indexInList": 0,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 0
  },
  {
    "encodedKey": "8a8080a254c4397d0154c4545f410037",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "LOAN_ACCOUNT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "LOAN_ACCOUNT_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "222",
    "indexInList": 2,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 1
  },
  {
    "encodedKey": "8a8080a254c4397d0154c4545f410039",
    "parentKey": "8a8080a254a98efe0154a99ad8c800fa",
    "customFieldKey": "8a8080a254c4397d0154c45093f4002a",
    "customField": {
      "encodedKey": "8a8080a254c4397d0154c45093f4002a",
      "id": "ccc1",
      "creationDate": "2016-05-18T14:41:36+0000",
      "lastModifiedDate": "2016-05-18T14:41:36+0000",
      "name": "cccc1",
      "type": "LOAN_ACCOUNT_INFO",
      "dataType": "STRING",
      "valueLength": "SHORT",
      "isDefault": false,
      "isRequired": false,
      "description": "",
      "customFieldSet": {
        "encodedKey": "8a8080a254c4397d0154c450633e0029",
        "name": "groupedcfs",
        "notes": "",
        "createdDate": "2016-05-18T14:41:23+0000",
        "indexInList": 2,
        "type": "LOAN_ACCOUNT_INFO",
        "usage": "GROUPED"
      },
      "indexInList": 14,
      "state": "NORMAL",
      "customFieldSelectionOptions": [],
      "viewRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002b",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "editRights": {
        "encodedKey": "8a8080a254c4397d0154c45093f4002c",
        "isAccessibleByAllUsers": false,
        "roles": []
      },
      "unique": false,
      "values": [],
      "amounts": {}
    },
    "value": "333",
    "indexInList": 4,
    "customFieldID": "ccc1",
    "customFieldSetGroupIndex": 2
  }
]

DELETE Loan Custom Field Values

Specific custom field values for a loan can be deleted based on loan id and custom field id.

Usage Example

// DELETE the custom field value based on the loan id(abc123) and on the custom field id(family_members)
DELETE /api/loans/abc123/custominformation/family_members

// DELETE the custom field value based on the loan key(40288a134887e7e9014887f0eb720003) and on the custom field key(8a27a878491d417601491d48203100d9)
DELETE /api/loans/40288a134887e7e9014887f0eb720003/custominformation/8a27a878491d417601491d48203100d9

Response

A 200 Response is returned if the loan custom field value was successfully deleted.

Note

You might see a property named "customFieldProductSettings" in the custom field object from loan and savings JSON. Please take in consideration that this property will be stripped from the accounts JSON content in the next release.

Set Settlement Account for Loan Account

Allows setting a settlement account for a loan account based on the loan and savings ids.

Usage examples

// set a settlement account for a loan account
POST api/loans/LOAN_ID/settlementAccounts/SAVINGS_ID

Samples response

// A success response will be returned if the settlement account has been set to the loan account.
{
  "returnCode": 0,
  "returnStatus": "SUCCESS"
}

Remove Settlement Account from Loan Account

Allows removing a settlement account link from a loan account based on the loan id savings ids.

Usage examples

// remove the settlement with savings encoded key "402880a7576fe5c601576feba6c9000f" for loan with key "402880e157573cf80157574326f60495"
DELETE /api/loans/402880e157573cf80157574326f60495/settlementAccounts/402880a7576fe5c601576feba6c9000f

// remove the settlement with savings id "ZEVS347" for loan with id "NLJX247"
DELETE /api/loans/NLJX247/settlementAccounts/ZEVS347

Samples response

// A success response will be returned if the settlement account has been removed from a loan account.
{
  "returnCode": 0,
  "returnStatus": "SUCCESS"
}

POST Search

Allows to retrieve loan accounts using dynamic custom filters.

Parameters

Parameter Value
filterConstraints A JSON array of constraints.
filterSelection The field on which the constraint will be applied. Available loan account filter selections can be found bellow.
filterElement The constraint operator. Available filter elements can be found bellow.
value The constraint value. Required for filter elements with one or two values.
secondValue The constraint second value. Required for filter elements with two values.
dataItemType The entity where the field on which to apply the constraint is located. If the field is located in the same entity with the entity being searched, this field is optional.

Available loan account filter values

Filter Selection Parameter Data Type
ACCOUNT_HOLDER_KEY KEY
PRODUCT_KEY KEY
LOAN_RISK_LEVEL_KEY KEY
ENCODED_KEY KEY
LOAN_NAME STRING
ACCOUNT_ID STRING
ACCOUNT_HOLDER_ID STRING
RECIPIENT STRING
CREATION_DATE DATE_UTC
APPROVAL_DATE DATE
LAST_MODIFIED_DATE DATE_UTC
LAST_SET_TO_ARREARS_DATE DATE
LAST_LOCKED_DATE DATE
CLOSED_DATE DATE
DAYS_IN_ARREARS NUMBER
DAYS_LATE NUMBER
ACCOUNT_SUB_STATE ENUM
ACCOUNT_STATE ENUM
LOAN_AMOUNT MONEY
DISBURSED_TRANCHES_AMOUNT MONEY
NUM_INSTALLMENTS NUMBER
PRINCIPAL_DUE MONEY
PRINCIPAL_PAID MONEY
PRINCIPAL_BALANCE MONEY
INTEREST_DUE MONEY
INTEREST_PAID MONEY
INTEREST_BALANCE MONEY
INTEREST_ACCRUED MONEY
FEES_DUE MONEY
FEES_BALANCE MONEY
FEES_PAID MONEY
PENALTY_CALCULATION_METHOD ENUM
PENALTY_DUE MONEY
PENALTY_PAID MONEY
PENALTY_BALANCE MONEY
PENALTY_ACCRUED MONEY
PENALTY_RATE BIG_DECIMAL
ARREARS_TOLERANCE_PERIOD NUMBER
INTEREST_RATE BIG_DECIMAL
INTEREST_SPREAD BIG_DECIMAL
TOTAL_PAID MONEY
TOTAL_BALANCE MONEY
TOTAL_DUE MONEY
FIRST_REPAYMENT_DATE DATE
LAST_PAYMENT_DATE DATE
LAST_PAYMENT_AMOUNT MONEY
EXPECTED_MATURITY_DATE DATE
RESCHEDULED_ACCOUNT_ID STRING
REFINANCED_ACCOUNT_ID STRING
ORIGINAL_ACCOUNT_ID STRING
TAX_RATE BIG_DECIMAL
TAX_PAID MONEY
TAX_DUE MONEY
HAS_SETTLEMENT_ACCOUNT BOOLEAN
INTEREST_COMMISSION BIG_DECIMAL
FUNDS_AMOUNT MONEY
FUNDING_PERCENTAGE BIG_DECIMAL
NUMBER_OF_FUNDS NUMBER
FUNDS_ENABLED BOOLEAN
AVAILABLE_AMOUNT MONEY
WAS_RESCHEDULED BOOLEAN
WAS_REFINANCED BOOLEAN
PREPAYMENTS_RECALCULATION ENUM
APPLY_INTEREST_ON_PREPAYMENT_METHOD ENUM
LATE_PAYMENT_RECALCULATION_METHOD ENUM
REDRAW_BALANCE MONEY
EXPECTED_PRINCIPAL_REDRAW MONEY

Available disbursement tranche filter values

Filter Selection Parameter Data Type
ENCODED_KEY KEY
PARENT_ACCOUNT_KEY KEY
DISBURSEMENT_TRANSACTION_KEY KEY
AMOUNT MONEY
EXPECTED_DISRBUSEMENT_DATE DATE

Available disbursement details filter values

Filter Selection Parameter Data Type
EXPECTED_DISBURSEMENT_DATE DATE
DISBURSEMENT_DATE DATE

Available filter elements

Filter Element Number Of affected values Available for
EQUALS ONE_VALUE BIG_DECIMAL,BOOLEAN,LONG,MONEY,NUMBER,PERCENT,STRING,ENUM,KEY
MORE_THAN ONE_VALUE BIG_DECIMAL,NUMBER,MONEY
LESS_THAN ONE_VALUE BIG_DECIMAL,NUMBER,MONEY
BETWEEN TWO_VALUES BIG_DECIMAL,NUMBER,MONEY,DATE,DATE_UTC
ON ONE_VALUE DATE,DATE_UTC
AFTER ONE_VALUE DATE,DATE_UTC
BEFORE ONE_VALUE DATE,DATE_UTC
STARTS_WITH ONE_VALUE STRING
IN LIST ENUM,KEY
TODAY NO_VALUE DATE,DATE_UTC
THIS_WEEK NO_VALUE DATE,DATE_UTC
THIS_MONTH NO_VALUE DATE,DATE_UTC
THIS_YEAR NO_VALUE DATE,DATE_UTC
LAST_DAYS ONE_VALUE DATE,DATE_UTC
EMPTY NO_VALUE BIG_DECIMAL,LONG,MONEY,NUMBER,PERCENT,STRING,ENUM,KEY,DATE,DATE_UTC
NOT_EMPTY NO_VALUE BIG_DECIMAL,LONG,MONEY,NUMBER,PERCENT,STRING,ENUM,KEY,DATE,DATE_UTC

Usage examples

// get all loan accounts that are having the balance between the given amounts
POST /api/loans/search
{
  "filterConstraints":[
      {
        "filterSelection":"LOAN_AMOUNT",
        "filterElement":"BETWEEN",
        "value":"1600",
        "secondValue":"1800"
      }
   ]
}

// get all closed loan accounts
POST {
  "filterConstraints":[
      {
        "filterSelection":"ACCOUNT_STATE",
        "filterElement":"EQUALS",
        "value":"CLOSED"
      }
   ]
} /api/loans/search

// get all loan accounts created this month
POST {
  "filterConstraints":[
      {
        "filterSelection":"CREATION_DATE",
        "filterElement":"THIS_MONTH"
      }
   ]
} /api/loans/search

// get all loan accounts that are having loan disbursement tranche with 100 amount
POST {
   "filterConstraints":[
      {
         "filterSelection":"AMOUNT",
         "dataItemType":"TRANCHE",
         "filterElement":"EQUALS",
         "value":"100"
      }
   ]
} /api/loans/search

Response

The loan accounts that match the search will be returned

POST Refinance

Allows to refinance a loan account with outstanding balance capitalization into a new loan account.

Note

Interest, fees and penalties can be capitalized into the new account as long as the same accounting methodology is in place for the new product. When a different accounting setting is met, the outstanding balance amounts have to be written off.

Parameters for JSON calls

action REFINANCE. Required.
loanAccount The new loan account to be created. Should have the same format as when POST a new loan account (including guarantors, custom fields etc). The amount should be the sum of the old balance and the top up amount mentioned above. Required.
restructureDetails Define the restructure details for refinancing the loan account (the top up amount). Required.
topUpAmount The amount that will be increased. Required.
interestWriteOff The amount of interest to be written off from the current interest balance when refinancing the original account. If this field is missing or zero, the whole amount will be capitalized. Optional.
feesWriteOff The amount of fees to be written off from the current fees balance when refinancing the original account. If this field is missing or zero, the whole amount will be capitalized. Optional.
penaltyWriteOff The amount of penalty to be written off from the current penalty balance when refinancing the original account. If this field is missing or zero, the whole amount will be capitalized. Optional.

Parameters for Custom Fields

customFieldID The custom field Id. Required.
value The custom field Value. Required.

Usage

//POST refinance a loan account to a simple new loan account
POST /api/loans/ABC123/action
{
    "action": "refinance",
    "loanAccount": {   
        "productTypeKey":"8a80808a5375ec9a015375ef13cd0351",
        "loanName":"Agriculture Loan",
        "id":"NEW_ACCOUNT",
        "loanAmount":"578.08",
        "interestRate":"2.5",
        "repaymentPeriodCount":1,
        "repaymentInstallments":4,
        "repaymentPeriodUnit":"MONTHS",
        "gracePeriod":0,
        "gracePeriodType":"NONE",
        "arrearsTolerancePeriod":23,
        "disbursementDetails":{
            "firstRepaymentDate":"2016-04-03"
        }
    },
    "restructureDetails": {
        "topUpAmount":"50"
    }
}
//POST refinance a loan account to a new account with many parameters (custom fields, guarantors, restructure details) using JSON.
POST /api/loans/ABC123/action
{
   "action":"REFINANCE",
   "loanAccount":{
      "productTypeKey":"40288a13437b71d201437b87af7d033f",
      "loanName":"Agriculture Loan",
      "id":"NEW_ACCOUNT",
      "loanAmount":"1150",
      "repaymentInstallments":5,
      "interestRate":"2.5",
      "repaymentPeriodCount":1,
      "repaymentPeriodUnit":"MONTHS",
      "gracePeriod":0,
      "gracePeriodType":"NONE",
      "arrearsTolerancePeriod":0,
      "firstRepaymentDate":"2014-01-13",
       "guarantees":[
         {
            "guarantorKey":"8a80806852f38c860152f38de0ad0019",
            "amount":"950",
            "guarantorType":"GUARANTOR",
            "customFieldValues":[
               {
                  "CustomFieldID":"Employement_status",
                  "value":"Self-employed"
               }
            ]
         }
      ]
      "notes":"some notes exa",
      "disbursementDetails":{
         "expectedDisbursementDate":"2016-01-08",
         "firstRepaymentDate":"2016-02-08"
      }
   },
   "customInformation":[
      {
         "value":"None",
         "customFieldID":"Special_Installements_Loan_Accou"
      }
   ],
   "restructureDetails":{
      "topUpAmount":"200.00",
      "interestWriteOff" : "10",
      "feesWriteOff" : "10", 
      "penaltyWriteOff" : "20"
   }
}

Response

A 201 Response is returned if the loans was successfully refinanced. The response Location header is set to the loan id and the new created loan object is also returned.

POST Reschedule

Allows to reschedule a loan account with outstanding balance capitalization into a new loan account.

Note

Interest, fees and penalties can be capitalized into the new account as long as the same accounting methodology is in place for the new product. When a different accounting setting is met, the outstanding balance amounts have to be written off.

Parameters for JSON calls

action RESCHEDULE. Required.
loanAccount The new loan account to be created. Should have the same format as when POST a new loan account (including guarantors, custom fields etc). The amount should be the difference between the old account balance and the amount to be written off if it is mentioned. Otherwise, the amount should be equal to the original account balance. Required.
restructureDetails Define the restructure details for rescheduling the loan account (the amount which will be written off)
principalWriteOff The amount of principal that will be written off when rescheduling the original account. Optional.
interestWriteOff The amount of interest to be written off from the current interest balance when rescheduling the original account. If this field is missing or zero, the whole amount will be capitalized. Optional.
feesWriteOff The amount of fees to be written off from the current fees balance when rescheduling the original account. If this field is missing or zero, the whole amount will be capitalized. Optional.
penaltyWriteOff The amount of penalty to be written off from the current penalty balance when rescheduling the original account. If this field is missing or zero, the whole amount will be capitalized. Optional.

Parameters for Custom Fields

customFieldID The custom field Id. Required.
value The custom field Value. Required.

Usage

//POST reschedule a loan account to a simple new loan account
POST /api/loans/ABC123/action
{
    "action": "reschedule",
    "loanAccount": {   
        "productTypeKey":"8a80808a5317de22015317de5b94034c",
        "loanName":"van1 damme7",
        "id":"test idd333",
        "loanAmount":"950",
        "repaymentInstallments":1,
        "interestRate":"2.5",
        "repaymentPeriodCount":1,
        "repaymentPeriodUnit":"MONTHS",
        "gracePeriod":0,
        "gracePeriodType":"NONE",
        "arrearsTolerancePeriod":0,
        "firstRepaymentDate":"2016-05-10",
        "notes":"some_notes",
        "disbursementDetails":{
            "firstRepaymentDate":"2016-04-03"
        }
    }
}
//POST reschedule a loan account to a new account with many parameters (custom fields, guarantors, restructure details) using JSON.
POST /api/loans/ABC123/action
{
   "action":"reschedule",
   "loanAccount":{
      "productTypeKey":"40288a13437b71d201437b87af7d033f",
      "loanName":"Agriculture Loan",
      "id":"NEW_ACCOUNT",
      "loanAmount":"1150",
      "repaymentInstallments":5,
      "interestRate":"2.5",
      "repaymentPeriodCount":1,
      "repaymentPeriodUnit":"MONTHS",
      "gracePeriod":0,
      "gracePeriodType":"NONE",
      "arrearsTolerancePeriod":0,
      "firstRepaymentDate":"2014-01-13",
       "guarantees":[
         {
            "guarantorKey":"8a80806852f38c860152f38de0ad0019",
            "amount":"950",
            "guarantorType":"GUARANTOR",
            "customFieldValues":[
               {
                  "CustomFieldID":"Employement_status",
                  "value":"Self-employed"
               }
            ]
         }
      ]
      "notes":"some_notes",
      "disbursementDetails":{
         "expectedDisbursementDate":"2016-01-08",
         "firstRepaymentDate":"2016-02-08"
      }
   },
   "customInformation":[
      {
         "value":"None",
         "customFieldID":"Special_Installements_Loan_Accou"
      }
   ],
   "restructureDetails":{
      "principalWriteOff":"200.00",
      "interestWriteOff" : "10",
      "feesWriteOff" : "10", 
      "penaltyWriteOff" : "20"
   }
}

Response

A 201 Response is returned if the loans was successfully rescheduled. The response Location header is set to the loan id and the new created loan object is also returned.
support@mambu.com
https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete