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):
fileTypetakes 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-typesand
GET /api/v4/loan-programs(or
GET /api/v4/loan-programs-internal) list what is available.primaryStatusIdmust be one of your company's active statuses,
fromGET /api/v4/loan-primary-statuses.branchId,brokerIdandloanOfficerIdmust 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),branchIdmust also be one of
the branches it lists inassignedBranches; another branch is a
422, reported underbranchIDwhichever 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.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||

