> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Lender REST API
> Orient yourself in the Lender API: the /api/v1 base path, bearer authentication, resource-and-action authorization, decimal-string money, scoped idempotency, pagination, the problem+json error shape, and the operations grouped by job.
Lender serves one HTTP API. Every operation sits under the base path `/api/v1`, and nothing versions in the host. A product list is `GET /api/v1/loan-products`.
This page is the map, not the territory. It covers what the operations share, then groups them by the job they do. Each operation has its own page under the **Lender** anchor in the [API Reference](/en/reference/introduction), with full request and response shapes.
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 SDK generation.
## Authentication
***
Lender accepts a JWT bearer token. One security scheme applies to the whole document:
```http theme={null}
Authorization: Bearer
```
Two reads are public and take no token: [list jurisdictions](/en/reference/lender/list-jurisdictions) and [get a jurisdiction](/en/reference/lender/get-jurisdiction). The registry is deployment metadata, so a client can read it before it has an identity.
The probes stay outside authentication so an orchestrator reaches them without a token: `/health`, `/readyz`, and `/version`.
### Authorization
***
Lender authorizes each request against the `lender` application, a resource, and an action. The resource follows the surface, and the actions are granular rather than one write:
| Resource | Actions |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loan_product` | `read`, `write` |
| `loan_applications` | `preview:schedule`, `create`, `approve`, `reject`, `withdraw`, `disburse`, `capitalization-consent:ingest`, `preview:tax` |
| `loan_accounts` | `read`, `audit:read`, `charge:apply`, `repayment:preview`, `repayment:record`, `repayment:reverse`, `prepayment:record`, `reschedule`, `cet:read`, `pdd:transition` |
| `accounting` | `read`, `write` |
| `streaming_manifest` | `read` |
Grant the officer role only the actions its job needs. `make generate-casdoor` writes Lender's roles and permissions to a seed file you load into your identity provider — [Prerequisites](/en/lender/lender-prerequisites) shows the minimum set for origination.
### Tenant and officer identity
***
**The tenant is never a header, a query parameter, or a body field.** Lender resolves it from the validated identity on the request. See [Multi-tenancy](/en/multi-tenancy).
The assigned officer comes from the token subject in the same way. No loan-application body carries an officer field, and no client-supplied value overrides the subject.
## Requests and responses
***
Every operation that carries a body sends and returns `application/json`.
**Send every money and rate field as a decimal string**, never as a JSON number — `"50000.00"`, `"0.01500000"`. Lender returns them the same way. Timestamps are RFC 3339 in UTC.
## Idempotency
***
The money and schedule writes accept an `X-Idempotency` request header.
| Operation | Header |
| ------------------------------------------------------------------------------ | ---------------------------------------------------- |
| [Disburse an application](/en/reference/lender/disburse-loan-application) | `X-Idempotency` required |
| [Apply a product charge](/en/reference/lender/create-loan-product-charges) | `X-Idempotency` required |
| [Prepay a loan account](/en/reference/lender/prepay-loan-account) | `X-Idempotency` required |
| [Prepay under the Brazil pack](/en/reference/lender/prepay-loan-account-br) | `X-Idempotency` required |
| [Reschedule a loan account](/en/reference/lender/reschedule-loan-account) | `X-Idempotency` required |
| [Record a repayment](/en/reference/lender/record-repayment) | `X-Request-ID`, with `X-Idempotency` as the fallback |
| [Reverse a transaction](/en/reference/lender/reverse-loan-account-transaction) | `X-Request-ID`, with `X-Idempotency` as the fallback |
Send your own key. The five operations that **require** `X-Idempotency` share one behaviour:
* A retry of a **completed** call replays the first response and stamps `X-Idempotency-Replayed: true` on it. Nothing is recorded a second time.
* A retry while the first call is still **in flight** answers `409`.
* The key is scoped to your tenant and expires after the window `IDEMPOTENCY_RETRY_WINDOW_SEC` sets, which defaults to 300 seconds.
Repayment and reversal work differently. Both read `X-Request-ID` first and fall back to `X-Idempotency` when it is absent. Send one of the two: a call that carries neither answers `422`.
Lender stores the request id in the database together with the facts of the call. A retry that carries the same id and the same facts replays the first response on the normal response path, with no replay header. The same request id with **different** facts answers `409` rather than replaying, so one id can never record two different amounts. That record does not expire.
The facts Lender compares differ by operation:
| Operation | Facts compared against the stored request id |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Record a repayment | The loan account, the amount, and the effective date (`transactionDate` when `effectiveDate` is absent). |
| Reverse a transaction | The transaction being reversed, the loan account, the reversal effective date, the reason, the profile version, and the jurisdiction code. The amount comes from the original transaction, so it is not compared. |
## Pagination
***
Paging is per operation, not global. Read the reference page for the operation you call, and send only the parameters it declares.
| Read | Parameters |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| [List loan products](/en/reference/lender/list-loan-products) and [list Brazilian loan products](/en/reference/lender/list-loan-products-br) | `limit` (default 25, ceiling 100) and `offset` (default 0, ceiling 10000) |
| [Audit events](/en/reference/lender/list-loan-account-audit-events-huma) | `limit` alone (default 50, ceiling 100) |
A value outside the range is rejected rather than clamped. Every other read declares its own parameters, so narrow it with the identifiers and filters on its reference page.
## Errors
***
Every error answers `application/problem+json` and follows [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457).
| Field | What it carries |
| -------- | -------------------------------------------------------------------------------------------------------------------- |
| `status` | The HTTP status code. |
| `title` | The status name. |
| `detail` | What went wrong on this occurrence. |
| `errors` | For a validation failure, one entry per field, each with a `location`, a `message`, and the `value` Lender received. |
Branch on the status and, for a `422`, on the `location` values in `errors`. A `422` names each field that failed. A server-side failure answers with a generic detail, so a raw cause never reaches a client.
## The operations by job
***
### Catalogue a product
Eight operations own the catalog. [Create a product](/en/reference/lender/create-loan-product) and [append a version](/en/reference/lender/create-loan-product-version) build the terms an application binds to. The version is immutable. [Bind an accounting profile](/en/reference/lender/create-loan-product-accounting-profile) maps each accounting event onto general-ledger accounts, and Lender needs it at disbursement. [Apply a charge](/en/reference/lender/create-loan-product-charges) and [read floating rates](/en/reference/lender/list-loan-product-floating-rates) complete the surface, alongside [list](/en/reference/lender/list-loan-products), [get](/en/reference/lender/get-loan-product), and [activate](/en/reference/lender/activate-loan-product). Read [Define a loan product](/en/lender/define-a-loan-product).
### Originate
Six operations carry an application from submitted to disbursed: [create](/en/reference/lender/create-loan-application), then one of [approve](/en/reference/lender/approve-loan-application), [reject](/en/reference/lender/reject-loan-application), or [withdraw](/en/reference/lender/withdraw-loan-application), then [disburse](/en/reference/lender/disburse-loan-application). [Preview a schedule](/en/reference/lender/preview-loan-schedule) computes installments for a quote and persists nothing.
The create and decide responses are the only reads of an application, so keep the body each call returns. Read [How origination works](/en/lender/how-origination-works) for the state machine and [Quick start](/en/lender/lender-quick-start) for the six calls end to end.
### Service a live loan
Five reads describe the account: [the account](/en/reference/lender/get-active-loan-account), [its schedule](/en/reference/lender/get-active-loan-schedule), [its transactions](/en/reference/lender/list-active-loan-transactions), [its charges](/en/reference/lender/list-active-loan-charges), and [its audit history](/en/reference/lender/list-loan-account-audit-events-huma).
Five writes move money or the schedule: [preview a repayment](/en/reference/lender/preview-repayment) before you [record it](/en/reference/lender/record-repayment), [prepay](/en/reference/lender/prepay-loan-account), [reschedule](/en/reference/lender/reschedule-loan-account), and [reverse a transaction](/en/reference/lender/reverse-loan-account-transaction). Nothing rewrites history. A reversal posts a new transaction that compensates the original. Read [Service a loan](/en/lender/service-a-loan).
### Account and book
[Start an accrual run](/en/reference/lender/create-accrual-run) recognizes interest for a competence period. [List journal references](/en/reference/lender/get-journal-reference) by correlation id and [read one](/en/reference/lender/get-journal-reference-by-id) to find the accounting record a run wrote. Read [Accounting and accrual runs](/en/lender/accounting-and-accrual-runs).
### Discover jurisdictions
The two public reads report which jurisdiction codes this deployment carries and what each profile decides. Read [Jurisdictions](/en/lender/jurisdictions).
### Brazil
The Brazil pack adds regulated reads and writes under `/api/v1/br`: [CET disclosure](/en/reference/lender/get-loan-account-cet-disclosure), [the credit-operation descriptor](/en/reference/lender/get-loan-account-credit-operation-descriptor), [PDD stage](/en/reference/lender/get-loan-account-pdd-stage) and [its transitions](/en/reference/lender/apply-loan-account-pdd-stage-transition), [a prepayment quote](/en/reference/lender/create-prepayment-quote) with [its payoff statement](/en/reference/lender/get-payoff-statement), [tax preview](/en/reference/lender/preview-tax), and [capitalization consent](/en/reference/lender/ingest-capitalization-clause-consent). The pack also carries its own product paths, which behave like the generic ones under Brazilian rules. Read [Brazil regulatory pack](/en/lender/brazil-regulatory-pack).
The payroll-deducted journey is an event conversation with the payroll rail, not a set of REST calls. Read [Consignado privado](/en/lender/consignado-privado).
## Next steps
***
Six calls from an empty database to a disbursed loan.
Subscribe to the credit journey instead of polling.
Every operation, with full request and response shapes.
The services, migrations, and configuration a first call needs.