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",
  "firstDueDate": "2026-07-14",
  "gracePeriodDays": 45,
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "requestedInstallmentAmount": "300.00",
  "requestedNetAmount": "10000.00",
  "requestedPrincipalAmount": "50000.00",
  "taxRegime": "brazilSimplesNacional"
}
'

201

{
  "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",
  "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",
  "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",
  "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>"
  }
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Idempotency · string · obrigatório

Canonical idempotency request ID (lib-commons enforcer reads this). 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.

Exemplo:

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

Corpo

application/json

borrowerDocument · string · obrigatório

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.

Exemplo:

"52998224725"

borrowerName · string · obrigatório

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

Exemplo:

"Maria da Silva"

expectedDisbursementDate · string · obrigatório

Expected disbursement date (RFC3339).

Exemplo:

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

loanProductVersionId · string · obrigatório

Loan product version identifier (UUID).

Exemplo:

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

requestedInstallments · integer<int64> · obrigatório

Number of installments. 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.

Intervalo obrigatório: 1 <= x <= 600

Exemplo:

24

requestedInterestRate · string · obrigatório

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

Exemplo:

"0.00000100"

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.

Exemplo:

"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.

Intervalo obrigatório: 0 <= x <= 365

Exemplo:

45

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.

Exemplo:

"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).

Exemplo:

"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).

Exemplo:

"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).

Exemplo:

"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.

Exemplo:

"brazilSimplesNacional"

Resposta

201

application/json

Created

assignedOfficerId · string · obrigatório

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.

Exemplo:

"officer-xyz"

borrowerId · string<uuid> · obrigatório

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

Exemplo:

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

expectedDisbursementDate · string · obrigatório

Expected disbursement date (RFC3339, UTC).

Exemplo:

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

id · string · obrigatório

Loan application identifier (UUID).

Exemplo:

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

loanProductVersionId · string · obrigatório

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

Exemplo:

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

previewJurisdictionCode · string · obrigatório

ISO-2 jurisdiction code resolved at preview time.

Exemplo:

"BR"

previewProfileVersion · string · obrigatório

Jurisdiction profile version resolved at preview time.

Exemplo:

"1.0.0"

requestedInstallments · integer<int64> · obrigatório

Number of installments requested.

Exemplo:

24

requestedInterestRate · string · obrigatório

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

Exemplo:

"0.00000100"

requestedPrincipalAmount · string · obrigatório

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.

Exemplo:

"50000.00"

status · string · obrigatório

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

Exemplo:

"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.

Exemplo:

"pessoaFisica"

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.

Exemplo:

"2026-07-14"

previewScheduleSnapshotId · string

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

Exemplo:

"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.

Exemplo:

"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.

Exemplo:

"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.

Exemplo:

"brazilSimplesNacional"

withdrawalDecision · object

Withdrawal facts; present only when the application is withdrawn.

Show child attributes