Skip to main content
Lender’s REST API is the whole client surface. Products, applications, loan accounts, accrual runs, and the Brazilian regulatory records are all HTTP calls under /api/v1. Nothing exists only inside a client library. Call Lender with the HTTP client your stack already has. There is no Lender client library to install, so the API is the contract you write against. This page covers what your client must handle and what to keep on your own side. It then covers how to place Lender behind a product your users already talk to. Read Lender REST API for the operations themselves.
The OpenAPI documents in this portal are render sources for the reference pages. They are not client contracts, and they are not a basis for client or SDK generation.

​
What your client must handle

Four rules cover most of the code you write against Lender.

​
Money travels as a decimal string

Money amounts are JSON decimal strings, normally with two decimal places. Decimal rates such as requestedInterestRate are strings with eight decimal places. The fixedAnnualRateBps, floatingSpreadBps, and annualRateBps fields are integer basis points:
Send the string, and parse the string with your language’s decimal type. A binary float loses cents, and a JSON number invites one. Timestamps are RFC 3339 in UTC.

​
Errors answer problem+json

Most operation and fallback errors answer application/problem+json. Do not assume that for 401 and 403 responses. Branch on status and content type. A schema-validation 422 can include an errors array with field details, while handler or domain validation can return only top-level detail. Treat detail as text for a person, not as a key your code matches on. A server-side failure answers with a generic detail on purpose, so no internal cause reaches a client. Log the status and your own correlation identifier, and let Lender’s traces carry the rest.

​
Retry your writes with your own key

The money and lifecycle writes take an idempotency key that you generate. They include the five loan-application writes, product charges, prepayment, reschedule, repayment, and reversal. Derive the key from your own request identifier, so a retry replays the first answer instead of writing a second time. The operations that require X-Idempotency replay a completed call with X-Idempotency-Replayed: true on the response. They answer 409 while the first call is still in flight. Repayment, reversal, and returned-payment collection key on X-Request-ID instead, and fall back to X-Idempotency when it is absent. A retry with the same facts replays. The same id with different facts answers 409. So branch on the response body, never on the presence of the replay header. The middleware fails closed during an idempotency-store outage: it refuses with 503 rather than letting an unprotected write through. Treat that refusal as “not executed, try again”, and reconcile before reaching for a new key. Lender REST API lists which header each of those operations takes, and how long a key lives.

​
Page with filters, not with deep offsets

Paging is per operation. The product list reads take limit and offset. The audit history takes limit alone. A value outside the declared range answers 422 rather than a quietly reduced page. Read the reference page for the operation you call, and narrow the query instead of walking a long offset.

​
Keep the identifiers your writes return

The origination operations are commands: create, approve, reject, withdraw, and disburse. Each one answers with the full application body. Its id identifies the loan application. After disbursement, disbursementEvent.loanAccountId identifies the loan account. Store both on your side as you go. Your own record then links your borrower to the loan account. Every servicing read starts from an identifier you already hold. The schedule, the transactions, the charges, and the audit history all key on the loan account.

​
Embedding Lender behind your own product

Lender is a service you deploy, not a library you link. To put it behind an application your customers already use, keep the credentials on your side and call Lender server to server. Four rules keep that boundary clean. Never hand a Lender token to a browser or a mobile app. Your service authenticates your user and decides whether that user may act. It then calls Lender with a token of its own. Mint the token for the person who acts. Lender derives the HTTP actor from the token subject, never from a request field. The assigned officer approves and rejects. Either the borrower or assigned officer may withdraw. The pinned jurisdiction’s actor policy governs approval and disbursement, so do not assume one human subject performs every transition. Hold one credential per tenant. A self-hosted Lender uses DEFAULT_TENANT_ID. On Lerian Cloud, the tenant comes from the validated identity, never from a header, a query parameter, or a body field, so your service holds one credential for every tenant it serves. Learn about state changes from events. Lender publishes business events through its outbox, and it does not start without the event backbone. Read Lender events.
A disbursement records its posting intent in the same database transaction that moves the application to disbursed. Lender relays it to Midaz only when the ledger relay is configured. Otherwise, the intent remains in the outbox. Do not treat a 200 on disburse as proof that the ledger already carries the entry. Read Accounting and accrual runs.

​
Next steps

Lender REST API

The base path, authentication, idempotency, and the operations by job.

Lender events

The wire contract and the events you can subscribe to.

Quick start

Seven calls from an empty database to a disbursed loan.

Prerequisites

The services, migrations, and configuration a first call needs.