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.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||

