Create a loan file

post

https://api.lendingwise.com/api/v4/loans

Creates a loan file. Send at least one borrower, a fileType, a
loanProgram, a starting primaryStatusId, and the branchID the
loan belongs to. You get the new loan back, with its numeric id.

Set the starting pipeline status with primaryStatusId — the id
from GET /api/v4/loan-primary-statuses. Only the id works here,
because your own company can rename its status labels, so a label is
not something you can write. The keys loanStatus and
primeStatusId are not accepted; sending either gets you a 422 that
points to primaryStatusId.

loanBrokerID is optional. Leave it out and the loan is given your
company's placeholder broker, which is normal — loans are often
created before a broker is named. The loan then reads back with
loanBrokerID as null, because a placeholder is not a broker to
show you. Send the borrowing entity, and its members, when the
loan is taken in the name of an LLC or a corporation.

Creating a loan also sets up the records every loan file needs,
works out the starting pipeline status, and starts any automation
your company has set up.

What gets checked (anything refused comes back as
422 VALIDATION_FAILED, with error.fields naming the field and
the reason):

fileType takes either one loan-type code or a list of them, and
every code must be one your company has set up. loanProgram
works the same way. GET /api/v4/loan-types and
GET /api/v4/loan-programs (or
GET /api/v4/loan-programs-internal) list what is available.
primaryStatusId must be one of your company's active statuses,
from GET /api/v4/loan-primary-statuses.
branchID, loanBrokerID and loanOfficerID must each point to
an active branch, broker or loan officer on your account.

Sensible defaults still apply: leaving out loanBrokerID still gets
you the placeholder broker. Only a value that genuinely cannot be
used is refused.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Create body — the shared write shape plus the create-required fields.

branchID

integer

required

Branch the loan belongs to — must be an active branch in your company (else 422).

fileType

required

length ≥ 1

Loan types on the file — loan-type codes your company has set up (moduleCode) from GET /api/v4/loan-types. A file may legitimately carry more than one: the back office's own File Type control is a multi-select, and the codes persist as one row each. Send a list, or a bare string for the single-code case (identical in effect). Every code is checked against the loan types your company is subscribed to — an unknown one is rejected with 422 and named in the message, including one sent alongside valid codes. This is the same shape GET returns, so a record read from the API can be saved straight back.

Each code may appear only once. The list is a set, so sending the same code twice is rejected with 422 rather than merged — if you get that error, whatever built the list added a code twice. Codes are compared ignoring case for this check, so "HMLO" and "hmlo" count as the same code.

loanProgram

string

required

Lending program — a code your company has set up (STCode) from GET /api/v4/loan-programs (or /loan-programs-internal). Unknown values → 422.

primaryStatusId

integer

required

The loan's pipeline status, written by its stable id — the id from GET /api/v4/loan-primary-statuses. The id is the only way to set a status, because your own company can rename its status labels. An id that is unknown, switched off, or belongs to another company is refused with a 422. The keys loanStatus and primeStatusId are not accepted; sending either is a 422.

loanBrokerID

integer

Originating broker — must be an active broker in your company when provided (else 422). Optional: leave it out and the loan is given your company's placeholder broker to hold the slot. Reading the loan back then reports loanBrokerID as null, because the placeholder is not a broker anyone can be shown or assign.

loanOfficerID

integer

Assigned loan officer — must be an active loan officer in your company when provided (else 422). Optional.

leadSource

string

length ≤ 50

Lead source label (optional, free text).

borrower

object

required

entity

object

Borrowing entity. Required (at least entityName) when borrowerType is an entity type.

properties

array of objects

Subject/collateral properties (multi-property supported; mark exactly one isPrimary). Persisted to the normalized property tables; the primary property's address also mirrors onto the loan.

properties

loan

object

Loan structure, rates, dates, and fees. Property valuation/income/expense fields are loan-level for now.

Every money field here has a ceiling, and a figure over it is refused rather than quietly rounded down. Go over and the whole request comes back 422 with the field named, so nothing is stored half-changed.

The limit counts the digits BEFORE the decimal point, which is why it is written as an exclusiveMaximum: anything below the figure shown fits, however many decimal places it carries. Most fields here stop below 10,000,000,000,000 and are not annotated individually. Fourteen stop sooner and each carries its own figure — among them three percentages, whose ceilings are low because the figure is kept to many decimal places rather than because the number itself is small (loanRehabFinancedPercent must stay under 1,000). The limits differ because the underlying figures are stored differently.

Responses

201Loan created. Returns the loan with its system-assigned numeric id.

400Your request body could not be read, so nothing was changed. error.details.reason says what the problem was.

401Your bearer token is missing, or it is not valid. Get a new one from POST /api/v4/authenticate and send it again.

415Your body is JSON, but it was not labelled as JSON, so it was not read and nothing was changed. Send it again with Content-Type: application/json.

422One or more of the values you sent cannot be used, so nothing was changed. error.fields names each field and says what was wrong.

429You have made too many calls, so this one was refused and nothing was changed. Retry-After says how many seconds to wait; sending the same request again after that works.

defaultAny other failure. The shape is the same as every other error reply, so the same code can read it.