> ## 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. # Create loan application > Creates a pending approval loan application from an already-previewed schedule snapshot. ## OpenAPI ````yaml /pt/openapi/v3-current/lender.yaml post /api/v1/loan-applications openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- Code-first OpenAPI 3.1 surface for the Lender service. Routes that move money are at-most-once per X-Idempotency: when one answers 5xx, the X-Idempotency-Fenced response header says whether that key is now refusing resends (true) or free to retry (false or absent). license: name: Lerian Studio General License title: Lender API version: 1.0.0 servers: - url: https://lender.sandbox.lerian.net security: - BearerAuth: [] tags: - description: >- Caller session projection: validated subject and effective permissions for the presented token. name: Session - description: >- Ledger accounting operations: journal entries and accrual postings for loan accounts. Operations under /api/v1/internal are back-office operations for the client's operators: they require a person's login, and a service credential gets 403. name: Accounting - description: >- Loan application intake and lifecycle: submission, decisioning, and status. name: LoanApplications - description: >- Loan product catalog: definition, versioning, and activation of lending products. name: LoanProducts - description: >- Loan account servicing operations: balances, schedules, and account-level actions. name: Loan Accounts - description: >- Portfolio dashboard read operations: aggregated portfolio and performance views. name: Dashboard - description: >- Jurisdiction registry: supported jurisdiction profiles and their capabilities. name: Jurisdictions - description: >- Jurisdiction-specific loan application operations (Brazil origination surface). name: Loan Applications - description: >- Tax computation operations for jurisdiction-specific lending (e.g. Brazil IOF). name: Tax - description: >- Brazil consignado privado operations: contract lifecycle, exclusion repair, and compensating adjustments. Operations under /api/v1/internal are back-office operations for the client's operators: they require a person's login, and a service credential gets 403. name: Consignado - description: >- Inbound record quarantine. Operations under /api/v1/internal are back-office operations for the client's operators: they require a person's login, and a service credential gets 403. name: Streaming - description: >- Credit-instrument document template registry: versioned drafting and publication of CCB clausulado. name: DocumentTemplates paths: /api/v1/loan-applications: post: tags: - LoanApplications summary: Create loan application description: >- Creates a pending approval loan application from an already-previewed schedule snapshot. operationId: createLoanApplication parameters: - description: >- 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. in: header name: X-Idempotency required: true schema: description: >- 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. examples: - 550e8400-e29b-41d4-a716-446655440003 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateLoanApplicationHumaRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/LoanApplicationHumaBody' description: Created headers: X-Idempotency-Replayed: description: >- "true" when this response replays a request already executed under the same X-Idempotency, so nothing ran a second time and no money moved again. Absent on a first execution. schema: type: string '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The at-most-once contract refused the request before any handler ran: no X-Idempotency header (IDEMPOTENCY_KEY_REQUIRED), a key under a spelling this service does not read (IDEMPOTENCY_KEY_HEADER_UNKNOWN), or a request that could not be scoped to a tenant (IDEMPOTENCY_TENANT_REQUIRED). The code is in the problem document's `code` member. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unauthorized '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Forbidden '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Conflict '413': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Request Entity Too Large '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Service Unavailable '504': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Gateway Timeout default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Any other status this operation may carry, rendered as a problem document — including a refusal produced ahead of the service, such as a gateway or ingress answering on its behalf. components: schemas: CreateLoanApplicationHumaRequest: additionalProperties: false properties: borrowerDocument: description: >- 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. examples: - '52998224725' type: string borrowerName: description: >- 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). examples: - Maria da Silva maxLength: 256 type: string expectedDisbursementDate: description: Expected disbursement date (RFC3339). examples: - '2026-06-14T12:00:00Z' type: string firstDueDate: description: >- 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. examples: - '2026-07-14' type: string gracePeriodDays: description: >- 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. examples: - 45 format: int64 maximum: 365 minimum: 0 type: integer loanProductVersionId: description: Loan product version identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string previewScheduleSnapshotId: description: >- 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. examples: - 6ba7b810-9dad-11d1-80b4-00c04fd430c8 format: uuid type: string requestedInstallmentAmount: description: >- 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). examples: - '300.00' type: string requestedInstallments: description: >- 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. examples: - 24 format: int64 maximum: 600 minimum: 1 type: integer requestedInterestRate: description: >- Requested monthly interest rate as a decimal string, scale 8 (e.g. "0.00000100"). examples: - '0.00000100' type: string requestedNetAmount: description: >- 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). examples: - '10000.00' type: string requestedPrincipalAmount: description: >- 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). examples: - '50000.00' type: string taxRegime: description: >- 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. examples: - brazilSimplesNacional type: string required: - loanProductVersionId - borrowerDocument - borrowerName - requestedInterestRate - requestedInstallments - expectedDisbursementDate type: object LoanApplicationHumaBody: additionalProperties: false properties: approvalDecision: $ref: '#/components/schemas/ApprovalDecisionHumaBody' description: >- Approval facts; present only when the application is approved or disbursed. assignedOfficerId: description: >- 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. examples: - officer-xyz type: string borrowerId: description: >- The borrower's holder id in the Midaz CRM of the product's institution (UUID). examples: - 550e8400-e29b-41d4-a716-446655440002 format: uuid type: string borrowerKind: description: >- 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. examples: - pessoaFisica type: string disbursementEvent: $ref: '#/components/schemas/DisbursementEventHumaBody' description: Disbursement facts; present only when the application is disbursed. expectedDisbursementDate: description: Expected disbursement date (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string firstDueDate: description: >- 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. examples: - '2026-07-14' type: string id: description: Loan application identifier (UUID). examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: string loanProductVersionId: description: Loan product version this application was created against (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string previewJurisdictionCode: description: ISO-2 jurisdiction code resolved at preview time. examples: - BR type: string previewProfileVersion: description: Jurisdiction profile version resolved at preview time. examples: - 1.0.0 type: string previewScheduleSnapshotId: description: >- Schedule offer this application cites (UUID). ABSENT when it cites none, which is allowed: simulating first is optional. examples: - 6ba7b810-9dad-11d1-80b4-00c04fd430c8 type: string rejectionDecision: $ref: '#/components/schemas/ReasonedDecisionHumaBody' description: Rejection facts; present only when the application is rejected. requestedInstallmentAmount: description: >- Instalment the proposal was asked by, as a decimal string, minor-unit precision scale 2. ABSENT when the proposal named another amount. examples: - '300.00' type: string requestedInstallments: description: Number of installments requested. examples: - 24 format: int64 type: integer requestedInterestRate: description: >- Requested monthly interest rate as a decimal string, scale 8 (e.g. "0.00000100"). examples: - '0.00000100' type: string requestedNetAmount: description: >- Net the proposal was asked by, as a decimal string, minor-unit precision scale 2. ABSENT when the proposal named another amount. examples: - '10000.00' type: string requestedPrincipalAmount: description: >- 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. examples: - '50000.00' type: string status: description: >- Lifecycle status: one of pending_approval, approved, rejected, withdrawn, disbursed. examples: - pending_approval type: string taxRegime: description: >- Tax regime the borrower declared at creation. ABSENT when none was declared, and the release uses the loan product version's regime. examples: - brazilSimplesNacional type: string withdrawalDecision: $ref: '#/components/schemas/ReasonedDecisionHumaBody' description: Withdrawal facts; present only when the application is withdrawn. required: - id - loanProductVersionId - borrowerId - assignedOfficerId - status - requestedPrincipalAmount - requestedInterestRate - requestedInstallments - expectedDisbursementDate - previewProfileVersion - previewJurisdictionCode type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ApprovalDecisionHumaBody: additionalProperties: false properties: approvedAmount: description: >- Approved amount as a decimal string, minor-unit precision scale 2 (e.g. "48000.00"). examples: - '48000.00' type: string decidedBy: description: Authenticated subject who approved the application. type: string decisionAt: description: Approval decision timestamp (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string id: description: Approval decision identifier (UUID). examples: - 9f1c2d3e-4b5a-6789-abcd-ef0123456789 type: string note: description: Optional approval note supplied by the deciding officer. type: string required: - id - approvedAmount - decisionAt - decidedBy type: object DisbursementEventHumaBody: additionalProperties: false properties: disbursedAt: description: Disbursement timestamp (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string grossRequestedAmount: description: >- Gross requested disbursement amount as a decimal string, minor-unit precision scale 2 (e.g. "50000.00"). examples: - '50000.00' type: string id: description: Disbursement event identifier (UUID). examples: - c3d4e5f6-a7b8-4901-acde-f01234567890 type: string ledgerCorrelationId: description: >- Correlation this disbursement's ledger posting is recorded under; GET /api/v1/journal-references?correlation_id= resolves it once the ledger acknowledged the posting and answers 404 until then. A payroll-rail disbursement names its own posting key. Omitted on a contract minted by a substantial renegotiation, whose opening entry is the renegotiation's recognition posting and not a disbursement posting. examples: - >- origination.disbursement:7c9e6679-7425-40de-944b-e07fc1f90ae7:disburse-2026-06-14-001 type: string loanAccountId: description: Loan account credited by this disbursement (UUID). examples: - 7c9e6679-7425-40de-944b-e07fc1f90ae7 type: string netDeliveredAmount: description: >- Net delivered disbursement amount as a decimal string, minor-unit precision scale 2 (e.g. "49500.00"). examples: - '49500.00' type: string originationFeeAmount: description: >- Origination fee retained from this release, scale 2: the product version's fee on a direct-credit release, the declared fee on a payroll-rail release, 0.00 when none. examples: - '130.00' type: string profileVersion: description: Jurisdiction profile version applied by the disbursement pipeline. examples: - 1.0.0 type: string required: - id - loanAccountId - grossRequestedAmount - netDeliveredAmount - originationFeeAmount - disbursedAt - profileVersion type: object ReasonedDecisionHumaBody: additionalProperties: false properties: decidedBy: description: Authenticated subject who recorded the decision. type: string decisionAt: description: Decision timestamp (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string id: description: Decision identifier (UUID) for the rejection or withdrawal. examples: - b2c3d4e5-f6a7-4890-9bcd-ef0123456789 type: string reason: description: Free-text reason for the rejection or withdrawal. type: string required: - id - decisionAt - decidedBy - reason type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.