Skip to main content
POST
/
v1
/
loans
Create a loan
curl --request POST \
  --url https://api-staging.bsa.ai/v1/loans \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": 123,
  "productId": 123,
  "principal": 123,
  "externalId": "<string>"
}
'

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.

Creates a loan against an existing customer using one of the configured loan products. The returned loan is already Active and ready for repayments. Loan terms (term length, repayment schedule, interest rate, amortization, etc.) are inherited from the chosen productId, so the request body carries only the three fields that vary per loan.

​
Request body

​
customerId
integer
required
The customer this loan is for.
​
productId
integer
required
The loan product to use. List available products via GET /v1/loan-products.
​
principal
number
required
Requested principal amount. Must be greater than 0 and within the product’s minPrincipal/maxPrincipal bounds. The full principal is approved and disbursed in the same call.
​
externalId
string
Optional partner-supplied identifier for the loan (e.g. your wallet transaction reference). The LMS enforces uniqueness — a duplicate externalId is rejected with aborted. Once set, you can reference the loan on every repayment route via /v1/loans/external/{externalId}/... instead of the numeric LMS id.

​
Example

curl -sf -X POST "$BASE/v1/loans" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 42,
    "productId": 1,
    "principal": 10000,
    "externalId": "halotel-tx-12345"
  }'

​
Response

200 OK returns the freshly-created and disbursed loan object. 
{
  "id": "501",
  "accountNo": "000000501",
  "customerId": "42",
  "customerName": "ext-ada-001 Customer",
  "loanProductId": "1",
  "loanProductName": "Halotel 7-Day Loan",
  "status": "Active",
  "principal": 10000,
  "approvedPrincipal": 10000,
  "currencyCode": "TZS",
  "termFrequency": 7,
  "numberOfRepayments": 1,
  "interestRatePerPeriod": 11,

  "principalDisbursed": 10000,
  "principalOutstanding": 10000,
  "interestCharged": 77,
  "interestOutstanding": 77,
  "totalRepayment": 0,
  "totalOutstanding": 10077,

  "nextDueDate": "2026-06-04",
  "nextDueAmount": 10077,
  "overdue": false,

  "repaymentSchedule": [
    {
      "period": 1,
      "fromDate": "2026-05-28",
      "dueDate": "2026-06-04",
      "complete": false,
      "principalDue": 10000,
      "principalOutstanding": 10000,
      "interestDue": 77,
      "interestOutstanding": 77,
      "totalDue": 10077,
      "totalOutstanding": 10077
    }
  ]
}
The id (string) is what every downstream call uses (repayments, get, etc.). totalOutstanding is the headline “how much is owed” amount; nextDueDate / nextDueAmount are the next instalment to collect.

​
Errors

CodeWhen
invalid_argumentMissing customerId / productId / principal, or principal <= 0
not_foundproductId or customerId does not exist
aborted / invalid_argumentprincipal outside the product’s allowed range, or the customer is in a state that disallows new loans