Update a loan file

Updates only the fields you send. Leave a field out and it is left
alone. Send an explicit null and the field is cleared, where the
field allows that. You'll get a 404 if the loan is not on your
processing company's account, or, when your access is limited to
your branches, if it is filed under a branch you are not assigned
to. The two 404s are identical, and nothing is saved.

What gets checked (anything refused comes back as
422 VALIDATION_FAILED, with error.fields naming the field and
the reason): the same checks as creating a loan, applied only to the
fields you actually send. A field you leave out is never checked.
When you do send them, fileType and loanProgram must be values
your company has set up — see GET /api/v4/loan-types and
GET /api/v4/loan-programs (or
GET /api/v4/loan-programs-internal). 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, a new branchId must also be one GET /api/v4/me lists in
assignedBranches; another branch is a 422, reported under
branchID whichever name you sent, and nothing is saved.

Updating a property? Name which one. Every entry in
properties[] needs the propertyId of the property it updates.
Leave the id out, or send 0, and the call is refused with
422 VALIDATION_FAILED keyed properties.{i}.propertyId. To add a
property rather than update one, use
POST /api/v4/loans/{id}/properties.

You can save a loan back exactly as you read it. This route
accepts the complete body that GET /api/v4/loans/{id} gave you —
every block, every explicit null, fileType in the list shape the
read produced, and each property's own propertyId. Fields marked
readOnly — the total loan amount, the display labels and the
ids — are accepted and ignored rather than refused, so you never
have to strip them out first. A readOnly value you send is not
stored; a read shows the back office's own figure as of its last
save. loanBaseLoanAmount is writable, and a value within one cent
of what a read returns is ignored, so the body you read still saves
back unchanged.

Moving the loan along the pipeline is primaryStatusId, the
id from GET /api/v4/loan-primary-statuses. An id that is
unknown, switched off, or belongs to another company is refused with
a 422 — the loan's status is never quietly reset. Leave the field
out, or send null, and the status stays as it is. The keys
loanStatus and primeStatusId are not accepted; sending either
gets you a 422 that points to primaryStatusId.

Setting sub-statuses is subStatusIds, a LIST of ids from
GET /api/v4/loan-sub-statuses. It REPLACES the file's whole set:
anything not in the list is un-checked, [] clears them all, and
omitting the field (or sending null) leaves them alone. So to ADD
one, send the ids the loan already has plus the new one. An unknown,
inactive, or cross-company id refuses the whole save with a 422,
which means a rejected request never removes anything.

Preview a change first with ?dryRun=true. The save runs exactly
as it would — the same checks, the same writes, the same automation —
and is then undone, so nothing is kept. You get the loan as it would read
afterwards plus
meta.dryRun: true and meta.effects: the automation the save would
set off, any scheduled actions it would cancel, and the email it would
queue. Compare data with GET /api/v4/loans/{id} to see everything
that would change. 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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
integer
required

Numeric loan-file id (LMRId).

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

Same shape as LoanCreate, every field optional (merge-patch). Move the pipeline status with primaryStatusId.

ONE EXCEPTION to "every field optional": every properties[] entry must carry propertyId. See PropertyUpdate.

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

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

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

integer

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
entity
object

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

properties
array of objects

Subject/collateral properties to UPDATE. Each entry must name the property it changes with propertyId. To ADD a property, use POST /api/v4/loans/{id}/properties.

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.

Responses

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