Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lms.bsa.ai/llms.txt

Use this file to discover all available pages before exploring further.

A loan is an extension of credit to a customer. Origination is a single call: POST /v1/loans submits the application, approves it, and disburses the full principal, returning a loan that is already Active. 
POST /v1/loans  ⇒  Active (with repayments) → Closed
There are no separate approve or disburse endpoints — those steps happen automatically inside POST /v1/loans. Reversals are available for admin/operational use:
From stateReversal
ActiveUndo disbursal — returns the loan to Approved
ApprovedUndo approval — returns the loan to Submitted and pending approval
Any with outstanding balanceWrite off the remaining balance

​
The loan object

​
id
string
Unique loan identifier.
​
accountNo
string
​
externalId
string
​
customerId
string
The customer this loan belongs to.
​
customerName
string
​
loanProductId
string
The product template this loan was created from. See Loan products.
​
loanProductName
string
​
status
string
Lifecycle status. Common values: Submitted and pending approval, Approved, Active, Closed (obligations met), Closed (written off).
​
principal
number
Requested principal amount.
​
approvedPrincipal
number
Approved principal (may differ from requested). Present after approval.
​
currencyCode
string
ISO-4217 currency code, e.g. TZS, USD.
​
termFrequency
integer
Loan term in units of frequency type.
​
numberOfRepayments
integer
How many installments the loan is scheduled across.
​
interestRatePerPeriod
number

​
Balance roll-up

These fields summarise what has been charged, paid, and is still owed across the loan. They appear on both list and detail responses; values default to 0 when the loan has just been disbursed or has been fully settled.
​
principalDisbursed
number
Principal amount actually paid out at disbursal.
​
principalPaid
number
Principal portion already repaid.
​
principalOutstanding
number
Principal portion still owed.
​
interestCharged
number
Total interest accrued over the life of the loan.
​
interestPaid
number
Interest already repaid.
​
interestOutstanding
number
Interest still owed.
​
feeCharged
number
Total fees charged.
​
feePaid
number
Fees already paid.
​
feeOutstanding
number
Fees still owed.
​
penaltyCharged
number
Total penalty charges applied (e.g. late fees).
​
penaltyPaid
number
Penalty portion already paid.
​
penaltyOutstanding
number
Penalty portion still owed.
​
totalRepayment
number
Sum of everything the customer has paid in across all components (principal + interest + fees + penalty).
​
totalOutstanding
number
Headline “what does the customer still owe” — sum of every outstanding field above. This is the number to display on the USSD / dashboard when telling the customer their debt.
​
totalOverpaid
number
Non-zero only when the loan status is Overpaid. The credit on the loan that needs to be refunded via Credit balance refund.

​
Next-due and schedule

​
nextDueDate
string
ISO-8601 (yyyy-MM-dd) date of the next unpaid instalment. Empty for fully-paid or closed loans.
​
nextDueAmount
number
Amount outstanding on that next-unpaid instalment (sum of the period’s outstanding principal + interest + fee + penalty). Zero when there is no next-due.
​
overdue
boolean
true when the loan is Active and has at least one past-due unpaid instalment. Computed server-side so partners don’t need to compare schedule dates against the current date themselves. Always false for non-Active loans — Closed (obligations met), Closed (written off), and Overpaid have already settled the obligation one way or the other.
​
repaymentSchedule
array of objects
Full amortisation table — one entry per instalment. Each period carries period, dueDate, complete, plus the principal{Due,Paid,Outstanding}, interest{Due,Paid,Outstanding}, fee{Due,Paid,Outstanding}, penalty{Due,Paid,Outstanding}, and total{Due,Paid,Outstanding} triplets.

​
Endpoints

MethodPathPurpose
POST/v1/loansCreate a loan — optional externalId in body
GET/v1/loansList loans — filterable by customerId, customerExternalId, and status
GET/v1/loans/external/{loan_external_id}Get by externalId (recommended)
GET/v1/loans/{loan_id}Get by LMS id
POST/v1/loans/external/{loan_external_id}/...Every repayment op in externalId form (recommended)
POST/v1/loans/{loan_id}/repayments[/...]Repayments in LMS-id form
POST/v1/loans/external/{loan_external_id}/undo-disbursalUndo disbursal by externalId (recommended)
POST/v1/loans/{loan_id}/undo-disbursalUndo disbursal by LMS id
POST/v1/loans/external/{loan_external_id}/undo-approvalUndo approval by externalId (recommended)
POST/v1/loans/{loan_id}/undo-approvalUndo approval by LMS id
DELETE/v1/loans/external/{loan_external_id}Delete by externalId (recommended)
DELETE/v1/loans/{loan_id}Delete by LMS id
POST/v1/loans/external/{loan_external_id}/adjust-disbursement-dateAdjust disbursement date by externalId (recommended)
POST/v1/loans/{loan_id}/adjust-disbursement-dateAdjust disbursement date by LMS id
PUT/v1/loans/{loan_id}Update a loan (pending only) — numeric only
POST/v1/loans/{loan_id}/writeoffWrite off — numeric only
Read, repayment, undo, and delete paths all support both forms; the externalId form is recommended for partner integrations. For repayment-side operations, see the Repayments section.