Skip to main content
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 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, 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

Authentication is deployment-configured. PLUGIN_AUTH_ENABLED defaults to true. When enabled, protected routes require a JWT bearer token:
On Lerian Cloud, Lender resolves the tenant from the tenantId claim of the validated identity. Two reads are public and take no token: list jurisdictions and get a 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: Grant the officer role only the actions its job needs. Lender defines its roles and permissions in a seed file you load into your identity provider. Prerequisites shows the minimum set for origination.

​
Tenant and officer identity

The tenant is never a header, a query parameter, or a body field. A self-hosted Lender uses DEFAULT_TENANT_ID. On Lerian Cloud, Lender resolves the tenant from the validated identity. 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 money amounts and decimal rates such as requestedInterestRate as decimal strings: "50000.00", "0.01500000". Product-version and floating-rate values fixedAnnualRateBps, floatingSpreadBps, and annualRateBps are integer basis points. Timestamps are RFC 3339 in UTC.

​
Idempotency

Lender holds 29 operations to an at-most-once contract, in two classes. The class decides which header you send and where the guarantee lives. Send your own key. On the 26 edge-enforced operations:
  • A retry of a completed call replays the first response and stamps X-Idempotency-Replayed: true on it. Lender records nothing a second time.
  • A retry while the first call is still in flight answers 409. Wait and read the resource. Do not send the command again.
  • A request carrying no key answers 400 with the code IDEMPOTENCY_KEY_REQUIRED. The key is a required header on the operation’s schema, so the refusal happens before any handler logic runs.
  • A key sent under a spelling Lender does not read (Idempotency-Key or X-Idempotency-Key) answers 400 with the code IDEMPOTENCY_KEY_HEADER_UNKNOWN, rather than executing the command unprotected. Sending one of those alongside the contract header is fine. The refusal fires only when X-Idempotency is absent.
  • Lender scopes the key to your tenant, and the key expires after the window IDEMPOTENCY_RETRY_WINDOW_SEC sets, which defaults to 86400 seconds (24 hours).
The contract is fail-closed, in both directions. A deployment with no reachable idempotency store does not start. If the store becomes unreachable while it runs, a guarded operation answers 503 with the code IDEMPOTENCY_UNAVAILABLE rather than executing unprotected. Every refusal carries a machine-readable code, and a client branches on it to choose between resending and reconciling. The IDEMPOTENCY_OUTCOME_UNKNOWN and IDEMPOTENCY_OUTCOME_UNKNOWN_UNFENCED codes say the request reached the handler and the outcome cannot be established. Read the resource before deciding. The refusal codes form a published contract. Renaming a code breaks that contract. The three transactional operations work differently. All 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:

​
Pagination

Paging is per operation, not global. Read the reference page for the operation you call, and send only the parameters it declares. Lender rejects a value outside the range rather than clamping it. Every other read declares its own parameters, so narrow it with the identifiers and filters on its reference page.

​
Errors

Huma and global-handler errors answer application/problem+json and follow RFC 9457. Authorization and idempotency middleware can use their own response formats. Branch on status and content type. For a 422, use errors when present. Handler or domain validation can return only top-level detail. 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 and append a version build the terms an application binds to. The version is immutable. Bind an accounting profile maps each accounting event onto general-ledger accounts, and activation requires it. Apply a charge and read floating rates complete the surface, alongside list, get, and activate. Read Define a loan product.

​
Originate

Six operations carry an application from submitted to disbursed: create, then one of approve, reject, or withdraw, then disburse. Preview a schedule computes installments for a quote and can record it as an offer. List and get read applications. Read How origination works for the state machine and Quick start for the seven calls end to end.

​
Service a live loan

Five reads describe the account: the account, its schedule, its transactions, its charges, and its audit history. Five writes move money or the schedule: preview a repayment before you record it, prepay, reschedule, and reverse a transaction. Nothing rewrites history. A reversal posts a new transaction that compensates the original. Read Service a loan.

​
Account and book

Start an accrual run recognizes interest for a competence period. List journal references by correlation id and read one to find the accounting record a run wrote. Read Accounting and accrual runs.

​
Discover jurisdictions

The two public reads report which jurisdiction codes this deployment carries and what each profile decides. Read Jurisdictions.

​
Brazil

The Brazil pack adds regulated reads and writes under /api/v1/br. They are CET disclosure, the credit-operation descriptor, PDD stage and its transitions, a prepayment quote with its payoff statement, tax preview, and capitalization consent. The pack also carries its own product paths, which behave like the generic ones under Brazilian rules. Read Brazil regulatory pack. The payroll-deducted journey is an event conversation with the payroll rail, not a set of REST calls. Read Consignado privado.

​
More surfaces

Each of these families has its own operations in the reference.
  • Assign receivables to a fund. /api/v1/assignment/... registers funds, assembles and scores sets of receivables against a fund’s eligibility rule, and approves or discards them. It also produces the offer file and the endorsement term, and ingests the administrator’s return file. It records externally-observed facts, registers a receivable’s credit instrument at the registradora, and works the exception queue.
  • Collect a returned payment. /api/v1/returned-payment-receivables lists and reads the separate borrower debts a reversed final payment opens when the contract it closed can no longer take the money back. It also records a collection against one.
  • Promote a product version. POST /api/v1/loan-products/{id}/promote repoints a live product at another of its versions. As a result, new applications originate on it, while contracts already written keep the version they were born on. The operation’s Brazil alias is /api/v1/br/loan-products/{id}/promote.
  • Read and revise product versions. /api/v1/loan-product-versions lists and reads the version snapshots, and declares a charge model revision on one. Under the Brazil pack, it also declares a version’s norm classification.
  • Template the documents. /api/v1/loan-products/{productId}/document-templates and the matching surface under an assignment fund draft, read, and publish the template versions Lender renders a generated document from.
  • Table the floating rates. /api/v1/rate-tables creates a floating-rate table and appends the periods Lender reads a floating product’s rate from.
  • Issue a credit instrument. /api/v1/loan-applications/{applicationId}/credit-instruments issues the instrument that evidences an application, lists the instruments issued, and downloads one.
  • Follow an accrual run. /api/v1/accrual-runs lists runs, reads one and its per-item decisions, and re-posts the recognitions the ledger has not acknowledged through POST /api/v1/accrual-runs/{id}/retry. The /api/v1/accounting-profiles surface lists the configured profiles. The supersession pair supersedes a product’s chart of accounts and settles the change onto every live contract’s balances.
  • Watch the portfolio. /api/v1/dashboard/portfolio and the two delinquency reads answer from the daily portfolio snapshot. The daily PDD promotion sweep builds that snapshot for its business date before it scans, and it ships enabled, so a default deployment has one. The separate core-daily-portfolio-snapshot job drives the same producer on its own schedule for deployments that want it built independently of the sweep.
  • Ladder the provision stages. /api/v1/br/pdd-stage-ladders publishes a PDD stage ladder version and reads the one in force.
  • Work the extraordinary collection. /api/v1/br/consignado/collection-instructions and the settlement pair list the open instructions, and ingest the collection agent’s Arquivo de Baixa Extraordinária. They also list the lines it refused. The operator surface under /api/v1/internal/br/consignado/... appoints the agent’s channel, works quarantined lines and inbox items, and disposes over-deduction refunds owed to workers.
  • Inspect the identity and the stream. GET /api/v1/me reports the session the token resolves to, and GET /api/v1/internal/streaming/discards lists the inbound records quarantined by the consumers.

​
Next steps

Quick start

Seven calls from an empty database to a disbursed loan.

Events

Subscribe to the credit journey instead of polling.

API Reference

Every operation, with full request and response shapes.

Prerequisites

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