Applications and underwriting
An application is underwritten in the call that records it. A borderline file goes to a credit officer, and an approved loan needs a closing before money moves.
The application
POST /loans takes an Idempotency-Key of 1 to 200 characters and answers 201 with the loan. Its status is the underwriting outcome: approved, declined or review. The same key with the same inputs returns the recorded loan. The same key with other inputs is 409 conflict.
customer_id, product_code, disbursement_account_idstringRequiredThe borrower, a live loan product, and an open deposit account of the borrower that the loan funds into and is paid from.
principal_amount, term_monthsintegerRequiredBoth positive. The principal is in minor units.
monthly_income_amount, monthly_debt_amountintegerRequiredIncome must be positive. Debt is the borrower's existing monthly obligations and cannot be negative.
credit_scoreintegerRequired300 to 850.
purpose, escrow_monthly_amount, guarantee, syndicateOptionalEscrow is accepted only on an escrowed product. A guarantee names the program (sba_7a, sba_504 or usda), guaranteed_bps and the agency's number.
The bank supplies the income, debt and score. The rules do not call a credit bureau or verify documents. POST /facilities works the same way, with limit_amount and settlement_account_id.
How the decision and the rate are set
- A principal or term outside the product's range is
declined. - A score below the product minimum is
declined. A score less than 60 points above it adds 200 basis points to the product rate. A score of 760 or more takes 50 off. dti_bpsis existing debt plus the estimated payment, over income. Above the product's limit by 500 basis points or less, the file goes toreview. Further above, it isdeclined.- A credit that would take the borrower past the legal lending limit is
declined.
The decision object keeps outcome, rate_bps, dti_bps, payment_amount and the reasons. The application publishes lending.application.approved, .declined or .review. The shipped term products are fixed rate. A variable-rate credit takes a signed rate contract, and each reset uses an index observation that a second person approved.
Review by a credit officer
POST /loans/{id}/decide takes decision (approve or decline) and reasons. POST /facilities/{id}/decisions is the same for a facility.
- The officer is staff with
operations:approveand a step-up within five minutes. The staff member who filed the application is refused with403. - A decline must state at least one reason. At most 10 reasons, each at most 300 characters.
- A credit that is not in
reviewanswers409. - The officer is recorded as
decision.decided_by, and the automated triggers move todecision.review_reasons.
Adverse action
A decline opens an adverse action record, and so does an approval above the product's rate, as a counteroffer. The record carries the reasons and a notice_due date 30 days after the decision. GET /loans/adverse-actions?open=true lists those with no notice yet. POST /loans/adverse-actions/{id}/notice records the method, a reference and sent_at. It does not send the notice.
Closing
A loan cannot be disbursed without a released closing. A construction facility, a HELOC and any facility secured by real estate need one before activation. Closing routes need staff with lending:write and a recent step-up. Reviews, consummation and release also need operations:approve and a person other than the maker.
| Step | Route under /loans/{id} | Body |
|---|---|---|
| Capture the plan | POST /closings | purpose (purchase, refinance, other), state, parties, policy_sha256, requirements, consummation_date, funding_date, first_payment_date, operating_calendar |
| Archive each document | POST /closings/{case}/documents | code, pdf (base64, at most 512 KiB), reference, signatures, receipts |
| Review each document, then the case | POST /closings/{case}/reviews/{subject} | approve, reason |
| Record the signing | POST /closings/{case}/consummation | at, which must fall on consummation_date |
| Release funding | POST /closings/{case}/release | reason, evidence_sha256 |
Every plan must list policy and signed_note as consummation requirements, and the borrower must be one of the parties. A consumer loan adds material_disclosures. A real-estate closing adds title, appraisal_review, flood_determination, hazard_insurance and security_instrument. Funding must fall within 60 days of consummation, and the first payment within 62 days after funding. A consumer loan on a principal dwelling, for any purpose but purchase, waits out the three-business-day rescission period before release. The closing's status reads proposed, approved, rejected, consummated, released, funded, cancelled or rescinded.
A residential mortgage also goes through /originations: six application items, then a calculated Loan Estimate and Closing Disclosure, each reviewed, issued as a PDF and recorded as delivered. It supports a fixed-rate purchase loan with one borrower.