Create loan application

Creates a pending approval loan application from an already-previewed schedule snapshot.

POST /api/v1/loan-applications

Create loan application

cURL

curl --request POST \
  --url https://lender.sandbox.lerian.net/api/v1/loan-applications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "borrowerDocument": "52998224725",
  "borrowerName": "Maria da Silva",
  "expectedDisbursementDate": "2026-06-14T12:00:00Z",
  "loanProductVersionId": "550e8400-e29b-41d4-a716-446655440000",
  "requestedInstallments": 24,
  "requestedInterestRate": "0.00000100",
  "amortizationSystem": "sac",
  "clientContractNumber": "CTR-2026-000123",
  "firstDueDate": "2026-07-14",
  "gracePeriodDays": 45,
  "paymentPeriodicity": "weekly",
  "paymentRules": [
    {
      "fromInstallment": 1,
      "kind": "interestOnly",
      "toInstallment": 6,
      "amount": "30000.00"
    }
  ],
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "requestedInstallmentAmount": "300.00",
  "requestedNetAmount": "10000.00",
  "requestedPrincipalAmount": "50000.00",
  "taxRegime": "brazilSimplesNacional"
}
'

201

{
  "amortizationSystem": "price",
  "assignedOfficerId": "officer-xyz",
  "borrowerId": "550e8400-e29b-41d4-a716-446655440002",
  "expectedDisbursementDate": "2026-06-14T12:00:00Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "loanProductVersionId": "550e8400-e29b-41d4-a716-446655440000",
  "paymentPeriodicity": "monthly",
  "previewJurisdictionCode": "BR",
  "previewProfileVersion": "1.0.0",
  "requestedInstallments": 24,
  "requestedInterestRate": "0.00000100",
  "requestedPrincipalAmount": "50000.00",
  "status": "pending_approval",
  "approvalDecision": {
    "approvedAmount": "48000.00",
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "9f1c2d3e-4b5a-6789-abcd-ef0123456789",
    "note": "<string>"
  },
  "borrowerKind": "pessoaFisica",
  "clientContractNumber": "CTR-2026-000123",
  "disbursementEvent": {
    "disbursedAt": "2026-06-14T12:00:00Z",
    "grossRequestedAmount": "50000.00",
    "id": "c3d4e5f6-a7b8-4901-acde-f01234567890",
    "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "netDeliveredAmount": "49500.00",
    "originationFeeAmount": "130.00",
    "profileVersion": "1.0.0",
    "ledgerCorrelationId": "origination.disbursement:7c9e6679-7425-40de-944b-e07fc1f90ae7:disburse-2026-06-14-001"
  },
  "firstDueDate": "2026-07-14",
  "paymentRules": [
    {
      "fromInstallment": 1,
      "kind": "interestOnly",
      "toInstallment": 6,
      "amount": "30000.00"
    }
  ],
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "rejectionDecision": {
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
    "reason": "<string>"
  },
  "requestedInstallmentAmount": "300.00",
  "requestedNetAmount": "10000.00",
  "taxRegime": "brazilSimplesNacional",
  "withdrawalDecision": {
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
    "reason": "<string>"
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Canonical idempotency request ID. Required: without a key a retry of this request cannot be told apart from a second instruction, and the duplicate it books is undone by hand.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440003"

Cuerpo

application/json

borrowerDocument · string · requerido

The borrower's CPF (11 digits) or CNPJ (14 characters, the alphanumeric CNPJ included); the mask's dots, dash, slash and spaces are ignored and the check digits must hold (LENDER-0258). It names whose credit this is: a CPF is a pessoaFisica, a CNPJ a pessoaJuridica, and the pinned product version must admit that kind (LENDER-0228). The Lender finds the borrower's holder by it in the Midaz CRM of the product's institution; the response's borrowerId is that holder. The proposal records that id, never the document.

Ejemplo:

"52998224725"

borrowerName · string · requerido

The borrower's name. A holder the Lender registers for this proposal carries it; an existing holder of the document keeps its own. The proposal never records it; blank refused (LENDER-0258).

Maximum string length: 256

Ejemplo:

"Maria da Silva"

expectedDisbursementDate · string · requerido

Expected disbursement date (RFC3339; midnight UTC names that civil day). A day after the São Paulo day three calendar months from today is refused (LENDER-0212); a past day is accepted.

Ejemplo:

"2026-06-14T12:00:00Z"

loanProductVersionId · string · requerido

Loan product version identifier (UUID).

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

requestedInstallments · integer<int64> · requerido

Number of installments, on the periodicity of the contract (paymentPeriodicity). Bounded, inclusive, by the loan product version's installment limits when it declares them (LENDER-0252). The term they span is bounded by its term limits (LENDER-0251): months from the expected disbursement day to the last instalment's grid date, a started month counting whole.

Rango requerido: 1 <= x <= 600

Ejemplo:

24

requestedInterestRate · string · requerido

Requested monthly interest rate as a decimal string, scale 8 (e.g. "0.00000100").

Ejemplo:

"0.00000100"

amortizationSystem · enum<string>

Amortization system the contract is struck under. OPTIONAL: omit it and the proposal asks for price. The loan product version must admit it (LENDER-0260).

Opciones disponibles: price, sac, american

Ejemplo:

"sac"

clientContractNumber · string

The client's own number for this contract. Written once, here; there is no route that sets or changes it later. Unique among the live contracts of the institution (LENDER-0248). Stored exactly as sent.

Maximum string length: 40

Pattern: ^[^\s\x00-\x1F\x7F](?:[^\x00-\x1F\x7F]*[^\s\x00-\x1F\x7F])?$

Ejemplo:

"CTR-2026-000123"

firstDueDate · string

Day the first instalment falls due (YYYY-MM-DD or RFC3339; an instant names the Brazilian civil day it falls on). OPTIONAL: omit it and the application records the day the schedule generator strikes for expectedDisbursementDate — one month later, moved to a business day. Bounded by the loan product version's admitted window, counted from the expected disbursement day (LENDER-0235). Mutually exclusive with gracePeriodDays (LENDER-0232). Every schedule of this application hangs on the recorded date: the credit instrument's table and the release.

Ejemplo:

"2026-07-14"

gracePeriodDays · integer<int64>

Carência in calendar days, in place of firstDueDate (LENDER-0232): the application records as its first due date the business day the schedule generator moves expectedDisbursementDate plus this many days to, the day a schedule preview with the same gracePeriodDays, loanProductVersionId and startDate strikes. Bounded by the loan product version's admitted window as a chosen firstDueDate is (LENDER-0235); zero is none. The application records only the date.

Rango requerido: 0 <= x <= 365

Ejemplo:

45

paymentPeriodicity · enum<string>

How often an instalment falls due. OPTIONAL: omit it and the proposal asks for monthly. The loan product version must admit it (LENDER-0260).

Opciones disponibles: monthly, fortnightly, weekly

Ejemplo:

"weekly"

paymentRules · object[] | null

Rows paid by rule instead of the system's share, in order and without overlap; a row with no rule follows the system and is the calculated instalment. Price or sac, monthly, only with requestedPrincipalAmount; the version must admit each kind (LENDER-0260); the last row cannot be interestOnly; every fixed total, the calculated instalment included, must exceed its period's interest (LENDER-0212); the last row closes the balance, so a fixedAmount there absorbs the rounding of the calculated instalment. A proposal with a fixedAmount rule is approved and released on the requested principal only (LENDER-0249), and a contract with rules releases once (LENDER-0262).

Maximum array length: 600

Show child attributes

previewScheduleSnapshotId · string<uuid>

Schedule offer this application cites: the scheduleOfferSnapshotId a schedule preview returned. OPTIONAL — an application does not have to be simulated first. When supplied it must name an offer on file, or the application is refused with LENDER-0236; its terms are never compared with the application's.

Ejemplo:

"6ba7b810-9dad-11d1-80b4-00c04fd430c8"

requestedInstallmentAmount · string

Instalment the proposal is asked by, as a decimal string, in place of requestedPrincipalAmount: a proposal names exactly one of this, requestedPrincipalAmount and requestedNetAmount (LENDER-0255). The loan product version must admit the installment amount anchor (LENDER-0254). The principal recorded is the largest, in cents, whose every instalment on the recorded first due date is at most this amount; when none is, LENDER-0256. The version's principal limits apply to the resolved principal: its maximum caps the search, and a principal below its minimum is refused (LENDER-0250).

Ejemplo:

"300.00"

requestedNetAmount · string

Net the borrower is to receive, as a decimal string, in place of requestedPrincipalAmount: a proposal names exactly one of this, requestedPrincipalAmount and requestedInstallmentAmount (LENDER-0255). The loan product version must admit the net amount anchor (LENDER-0254). The principal recorded is the least gross, in cents, whose release on the expected disbursement day delivers this amount after the jurisdiction withholding and the origination fee, or 0.01 above it. A fee that takes the whole net is refused with LENDER-0209, and a borrower kind the deployment prices no tax for with LENDER-0233. The version's principal limits apply to the resolved gross and never cap it (LENDER-0250).

Ejemplo:

"10000.00"

requestedPrincipalAmount · string

Requested principal amount as a decimal string (e.g. "50000.00"). A proposal names exactly one of this, requestedInstallmentAmount and requestedNetAmount (LENDER-0255). Bounded, inclusive, by the loan product version's principal limits when it declares them (LENDER-0250).

Ejemplo:

"50000.00"

taxRegime · string

Tax regime the borrower declared. OPTIONAL: omit it and the release uses the loan product version's own regime: on a version whose own regime is brazilSimplesNacional a pessoaJuridica is priced as an optante, and anyone else at the borrower kind's rate. It must be one of the regimes the version admits (LENDER-0930), which GET /api/v1/br/loan-product-versions/{id}/tax-regimes lists. brazilSimplesNacional is for a pessoaJuridica opting into the Simples Nacional, MEI included (LENDER-0931): the release withholds the IOF of Decreto 6.306/2007, art. 7o, VI, 0.00274% a day plus 0.38%, while the operation's contracted principal is R$ 30.000,00 or less, and the pessoaJuridica rate above it. The client keeps the borrower's art. 45, II declaration; the application records only the regime.

Ejemplo:

"brazilSimplesNacional"

Respuesta

201

application/json

Created

amortizationSystem · enum<string> · requerido

Amortization system the contract is struck under; price when the proposal asked for none.

Opciones disponibles: price, sac, american

Ejemplo:

"price"

assignedOfficerId · string · requerido

Authenticated officer who created the application (request subject), or empty on a system-originated application, which has no human officer. Whatever the identity provider issues as the subject: not necessarily a UUID, at most 255 characters.

Ejemplo:

"officer-xyz"

borrowerId · string<uuid> · requerido

The borrower's holder id in the Midaz CRM of the product's institution (UUID).

Ejemplo:

"550e8400-e29b-41d4-a716-446655440002"

expectedDisbursementDate · string · requerido

Expected disbursement date (RFC3339, UTC).

Ejemplo:

"2026-06-14T12:00:00Z"

id · string · requerido

Loan application identifier (UUID).

Ejemplo:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

loanProductVersionId · string · requerido

Loan product version this application was created against (UUID).

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

paymentPeriodicity · enum<string> · requerido

How often an instalment falls due; monthly when the proposal asked for none.

Opciones disponibles: monthly, fortnightly, weekly

Ejemplo:

"monthly"

previewJurisdictionCode · string · requerido

ISO-2 jurisdiction code resolved at preview time.

Ejemplo:

"BR"

previewProfileVersion · string · requerido

Jurisdiction profile version resolved at preview time.

Ejemplo:

"1.0.0"

requestedInstallments · integer<int64> · requerido

Number of installments requested, on the periodicity of the contract.

Ejemplo:

24

requestedInterestRate · string · requerido

Requested monthly interest rate as a decimal string, scale 8 (e.g. "0.00000100").

Ejemplo:

"0.00000100"

requestedPrincipalAmount · string · requerido

Requested principal amount as a decimal string, minor-unit precision scale 2 (e.g. "50000.00"). On a proposal asked by its instalment, the principal the Lender resolved for it; on one asked by its net, the gross the Lender resolved for it.

Ejemplo:

"50000.00"

status · string · requerido

Lifecycle status: one of pending_approval, approved, rejected, withdrawn, disbursed.

Ejemplo:

"pending_approval"

approvalDecision · object

Approval facts; present only when the application is approved or disbursed.

Show child attributes

borrowerKind · string

Whose credit this is: pessoaFisica for a CPF borrowerDocument, pessoaJuridica for a CNPJ. ABSENT on an application created before the declaration existed: such an application cannot be taxed or described, and the paths that need the kind refuse it with LENDER-0230 rather than assuming one.

Ejemplo:

"pessoaFisica"

clientContractNumber · string

The client's own number for this contract, exactly as recorded at creation. ABSENT when the contract has none.

Ejemplo:

"CTR-2026-000123"

disbursementEvent · object

Disbursement facts; present only when the application is disbursed.

Show child attributes

firstDueDate · string

First instalment date the application records (YYYY-MM-DD). ABSENT on an application created before the date was recorded, on a payroll-rail application and on a renegotiated contract.

Ejemplo:

"2026-07-14"

paymentRules · object[] | null

Rows the proposal pays by rule instead of the system's share, as sent. ABSENT when the ladder is the system's alone.

Show child attributes

previewScheduleSnapshotId · string

Schedule offer this application cites (UUID). ABSENT when it cites none, which is allowed: simulating first is optional.

Ejemplo:

"6ba7b810-9dad-11d1-80b4-00c04fd430c8"

rejectionDecision · object

Rejection facts; present only when the application is rejected.

Show child attributes

requestedInstallmentAmount · string

Instalment the proposal was asked by, as a decimal string, minor-unit precision scale 2. ABSENT when the proposal named another amount.

Ejemplo:

"300.00"

requestedNetAmount · string

Net the proposal was asked by, as a decimal string, minor-unit precision scale 2. ABSENT when the proposal named another amount.

Ejemplo:

"10000.00"

taxRegime · string

Tax regime the borrower declared at creation. ABSENT when none was declared, and the release uses the loan product version's regime.

Ejemplo:

"brazilSimplesNacional"

withdrawalDecision · object

Withdrawal facts; present only when the application is withdrawn.

Show child attributes