Create a loan file

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.

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

Preview it first with ?dryRun=true. The create runs exactly as it
would — the same checks, the same automation, the same notices — and is
then undone, so nothing is kept: no loan, no borrower profile, no queued
email. You get 200 (not 201) with the loan as it would read, plus
meta.dryRun: true and meta.effects, which lists the automation the
create would set off and the email it would queue. The id in a dry
run's data belongs to a loan that was never kept; do not use it. An
Idempotency-Key sent with a dry run is ignored: it is not reserved, so
the real call with that key behaves as if the dry run never happened.
dryRun goes in the query string; a dryRun in the body is refused with
a 422, so a preview is never applied by mistake. If the change cannot be
previewed safely, the answer is 409 RESOURCE_CONFLICT with
error.details.reason: DRY_RUN_UNSAFE, and nothing is saved.

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, brokerId and loanOfficerId must each point to
    an active branch, broker or loan officer on your account. When
    your access is limited to your branches (GET /api/v4/me,
    branchRestrictionsEnforced: true), branchId must also be one of
    the branches it lists in assignedBranches; another branch is a
    422, reported under branchID whichever name you sent, before
    anything is saved or previewed.

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

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
boolean
Defaults to false

Preview the write instead of making it. The request runs exactly as it
would and is then undone; nothing is kept. The answer carries
meta.dryRun: true and meta.effects. Send it in the query string —
a dryRun in the body is refused with a 422. true/false, 1/0
and yes/no are accepted; any other value is refused with a 422.
Send it only to a server whose responses carry
X-LW-Capabilities: loan-dry-run: a server older than the dry run
ignores the parameter and makes the change.
It is spelled exactly dryRun: dryrun, DryRun or dry_run is
refused with a 422 rather than ignored, and so is dryRun on any
other write route, because ignoring it would make the change for real.
A change that cannot be previewed safely answers
409 RESOURCE_CONFLICT with error.details.reason: DRY_RUN_UNSAFE.

Body Params

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

⛔ subStatusIds is NOT accepted here (nor the retired singular subStatusId): sub-statuses can only be set once the loan exists, and POST /api/v4/loans refuses either with a 422. That refusal is enforced by the route's own request rules, and is stated here and on the field itself rather than expressed as a schema subtraction — ⛔ do NOT add not: {} to express it. That construct was the only one of its kind on the v4 surface, it broke this reference's published page on readme.io (ERR-FYBC1O) and it rendered the excluded field in Body Params anyway, which is the opposite of what it claimed. PropertyCreate records the same history, and a test bans the keyword across the whole surface.

integer
deprecated

Deprecated — use branchId. Still accepted, and means exactly what branchId means, until it is removed on a date announced in the API changelog, 90 days after the announcement. Sending both names with different values: on a PATCH the one that differs from the stored value is the edit; otherwise it is a 422 naming both.

integer
required

Branch the loan belongs to — must be an active branch in your company (else 422), and, when your access is limited to your branches, one of those GET /api/v4/me lists in assignedBranches (else 422). ⚠️ Changing it on PATCH /loans/{id} moves the file (the branch column and its tblFileResponse.executiveId mirror) and nothing else. PATCH /loans/{id}/branch also files the client referral and the new branch's preferred-agent link for the current broker, writes a Branch changed … system note and queues the assignment mail — use that route when the move should be recorded on the file and announced.

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. Since API 4.1 each code must also be one the file's branch offers (the branch sent, else the file's own), because the back office's File Type control lists only the branch's types: another one is a 422 naming what the branch offers. A code the file already carries is exempt. 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.

A list you send REPLACES the whole set, so include every code the file should end up with, not just the one you are adding. This field is the exception to "send null and the field is cleared": on PATCH, neither null nor [] empties the loan types — both answer 200 and leave them exactly as they were, so a caller reading only the status would believe it had cleared the field. There is no way to remove a file's last loan type through this route. On POST the two spellings differ: fileType is required there, and [] is refused with "The file type field is required."

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.

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.

subStatusIds
array of integers

PATCH-ONLY. POST /api/v4/loans refuses this field with a 422 — sub-statuses can only be set after the loan exists.

The file's COMPLETE set of sub-statuses, as ids from GET /api/v4/loan-sub-statuses. This REPLACES what is on the file: any sub-status not in the list is un-checked, including ones a back-office user ticked by hand. To add one, read subStatuses from the loan and send the existing ids plus the new one — this is always safe, even for an id GET /api/v4/loan-sub-statuses has since dropped (a loan type your company unsubscribed from): an id already on the file is kept without being re-validated, so echoing it back unchanged never 422s. Only a genuinely NEW id must be one of your company's active, subscribed sub-statuses.

[] clears every sub-status. Omitting the field, or sending null, leaves them untouched — those are the only two ways to say "no change", and [] is not one of them. A single id is also accepted and means a one-element set. Every id must be an active sub-status in your company, and one bad id refuses the WHOLE save with a 422, so a rejected request never removes anything. The retired singular subStatusId is refused with a 422 pointing here.

subStatusIds
integer
deprecated

Deprecated — use brokerId. Still accepted, and means exactly what brokerId means, until it is removed on a date announced in the API changelog, 90 days after the announcement. Sending both names with different values: on a PATCH the one that differs from the stored value is the edit; otherwise it is a 422 naming both.

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 brokerId as null, because the placeholder is not a broker anyone can be shown or assign — except to a company API key (a tenant API key or a legacy token), which reads the placeholder's own id, as this API has always reported it. A company API key may send any of its company's placeholder ids, on POST or PATCH, and it is stored as sent, as this API has always done: a create is given that placeholder, a PATCH moves the loan onto it (which is how an API key unassigns a broker; the loan's last-updated time moves, and there is no Broker changed note or assignment notification), and sending back the placeholder the loan already has changes nothing. Another company's placeholder is a 422, and so is the placeholder from anyone signed in as a person or through MCP. ⚠️ Changing it on PATCH /api/v4/loans/{id} does everything PATCH /api/v4/loans/{id}/broker does — the client referral row, the branch's preferred-agent link, the file's last-updated stamp, a Broker changed … system note and the assignment notification — so the two routes are one operation. Sending the broker the loan already has does nothing. On POST /api/v4/loans the broker is recorded with the referral row only.

integer
deprecated

Deprecated — use loanOfficerId. Still accepted, and means exactly what loanOfficerId means, until it is removed on a date announced in the API changelog, 90 days after the announcement. Sending both names with different values: on a PATCH the one that differs from the stored value is the edit; otherwise it is a 422 naming both.

integer

Assigned loan officer — must be an active loan officer in your company when provided (else 422). Optional. ⚠️ Changing it on PATCH /loans/{id} writes the loan-officer column and nothing else. PATCH /loans/{id}/loan-officer also files the client referral and the preferred-agent link on the file's branch, writes a Loan Officer changed … system note and queues the assignment mail — use that route when the change should be recorded on the file and announced. (brokerId is the exception: the loan PATCH runs the broker route's full sequence.)

string
length ≤ 50

Lead source label (optional, free text).

string
length ≤ 60

Your own reference for this file, from whatever system you run alongside ours — free text, and we do not check it for uniqueness. It is the same field the back office shows on the Bor Info tab under Admin Info as "3rd party file ID", so a value typed there comes back here and a value sent here shows up there. Send null to clear it (an empty string is treated the same); leave the key out to keep the stored value. ⚠️ Unlike leadSource, where null leaves the field as it was.

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 two percentages, whose ceilings are low because the figure is kept to many decimal places rather than because the number itself is small (loanBrokerFeePercent and loanOriginationFeePercent must stay under 10,000). The limits differ because the underlying figures are stored differently.

Headers
string
length ≤ 64

A key you generate — a UUID is the usual choice — that makes it safe to
retry this request after a timeout.

The problem it solves. If a call times out you cannot tell whether
it landed. Retrying without a key creates a SECOND record. Retrying with
the same key returns the original result instead, and creates nothing.

  • Same key, same body → the original result, plus Idempotency-Replayed: true.
  • Same key, different body → 409. That means a bug in your code, not
    a safe retry, so the request is refused rather than guessed at.
  • No key → exactly the behaviour this endpoint has always had. The header
    is optional and nothing changes for callers that omit it.

A replay reflects the record's CURRENT state, not a byte-for-byte
copy of the original reply. If something else changed the record between
your first call and your retry, you see the change. We do this rather
than caching response bodies, because these replies carry borrower
personal data and we will not keep a copy of it at rest to serve a retry.

For the same reason a replay does not repeat meta.automation — the
automation ran once, on the original call, and saying otherwise would be
a lie about what just happened.

Keys are scoped to your own account and kept for 24 hours. After
that the key is forgotten and reusing it creates a new record, so retry
within a day. A key is at most 64 characters.

Responses

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json