Skip to main content
POST
Create a loan
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

string
required
The externalId of the customer this loan is for — the identifier you chose when creating the customer, not the numeric LMS id. The service resolves it against the LMS before submitting anything; an unknown externalId fails with not_found and no loan is created.
integer
required
The loan product to use. List available products via GET /v1/loan-products.
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.
string
Optional partner-supplied identifier for the loan (e.g. your wallet transaction reference). The LMS enforces uniqueness — a duplicate externalId is rejected with 409 already_exists (loan_external_id_exists). Once set, you can reference the loan on every repayment route via /v1/loans/external/{externalId}/... instead of the numeric LMS id.

Example

Response

200 OK returns the freshly-created and disbursed loan object.
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 maturity date and the amount owed by it. dueDateTime is the exact instant the loan falls due and the overdue penalty fires if it is still unpaid.
disbursedAt and dueDateTime on this response are computed from the instant the disbursal was confirmed. Subsequent reads serve them from the loan’s penalty schedule, which the platform records within about fifteen minutes; a GET in those first minutes may omit the two fields. The values agree to the second once present.
Asymmetry to be aware of: the request customerId carries the customer’s externalId, but the response customerId is the numeric LMS id (as a string) — the same value every read endpoint returns. Your externalId still appears on the customer object itself.

Errors