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 '
{
  "borrowerId": "550e8400-e29b-41d4-a716-446655440002",
  "borrowerKind": "pessoaFisica",
  "expectedDisbursementDate": "2026-06-14T12:00:00Z",
  "loanProductVersionId": "550e8400-e29b-41d4-a716-446655440000",
  "requestedInstallments": 24,
  "requestedInterestRate": "0.00000100",
  "requestedPrincipalAmount": "50000.00",
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
'

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",
    "profileVersion": "1.0.0"
  },
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "rejectionDecision": {
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
    "reason": "<string>"
  },
  "withdrawalDecision": {
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
    "reason": "<string>"
  }
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

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.

Example:

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

Body

application/json

borrowerId · string<uuid> · required

Borrower identifier (UUID).

Example:

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

borrowerKind · enum<string> · required

Whose credit this is: the taxpayer kind of the borrower, as established by the KYC the client performed. REQUIRED. Brazil charges a different daily IOF aliquota per kind (Decreto 6.306/2007, art. 7o, I, "b"), so the withholding cannot be computed without it and the service will not guess. The pinned product version must admit the kind named here, or the application is refused with 422 LENDER-0228; a version that declared no kinds admits none.

Available options: pessoaFisica, pessoaJuridica

Example:

"pessoaFisica"

expectedDisbursementDate · string · required

Expected disbursement date (RFC3339).

Example:

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

loanProductVersionId · string · required

Loan product version identifier (UUID).

Example:

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

requestedInstallments · integer<int64> · required

Number of installments.

Required range: 1 <= x <= 600

Example:

24

requestedInterestRate · string · required

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

Example:

"0.00000100"

requestedPrincipalAmount · string · required

Requested principal amount as a decimal string (e.g. "50000.00").

Example:

"50000.00"

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.

Example:

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

Response

201

application/json

Created

assignedOfficerId · string · required

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.

Example:

"officer-xyz"

borrowerId · string<uuid> · required

Borrower identifier (UUID).

Example:

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

expectedDisbursementDate · string · required

Expected disbursement date (RFC3339, UTC).

Example:

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

id · string · required

Loan application identifier (UUID).

Example:

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

loanProductVersionId · string · required

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

Example:

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

previewJurisdictionCode · string · required

ISO-2 jurisdiction code resolved at preview time.

Example:

"BR"

previewProfileVersion · string · required

Jurisdiction profile version resolved at preview time.

Example:

"1.0.0"

requestedInstallments · integer<int64> · required

Number of installments requested.

Example:

24

requestedInterestRate · string · required

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

Example:

"0.00000100"

requestedPrincipalAmount · string · required

Requested principal amount as a decimal string, minor-unit precision scale 2 (e.g. "50000.00").

Example:

"50000.00"

status · string · required

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

Example:

"pending_approval"

approvalDecision · object

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

Show child attributes

borrowerKind · string

Whose credit this is, as declared at creation. 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.

Example:

"pessoaFisica"

disbursementEvent · object

Disbursement facts; present only when the application is disbursed.

Show child attributes

previewScheduleSnapshotId · string

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

Example:

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

rejectionDecision · object

Rejection facts; present only when the application is rejected.

Show child attributes

withdrawalDecision · object

Withdrawal facts; present only when the application is withdrawn.

Show child attributes