Add subject properties to a loan

Adds one or more subject properties to a loan that already exists.

Each route does exactly one job:

propertyIdwhat it does
PATCH /api/v4/loans/{id}requiredupdates the properties you name
POST /api/v4/loans/{id}/propertiesnot acceptedadds new properties

You get back the properties this call created, and nothing else — a
list, in the order you sent them, each carrying the propertyId the
platform assigned. Send two properties and you get two entries; send
one and you get a list of one, so there is no need to check the count
before reading the reply. The loan's other properties are not
included; read those with GET /api/v4/loans/{id}.

⚠️ A company API key (a tenant API key or a legacy token) gets the
reply this API has always given instead: the WHOLE loan, in the shape
GET /api/v4/loans/{id} returns, with every property on it (the new
ones carry their propertyId), meta.automation when your company has
automation on, and no meta.count. A retry with the same
Idempotency-Key returns the whole loan again and adds nothing.

Properties already on the loan are left alone. Set isPrimary: true
on an entry to make that property the loan's primary one. Doing so
steps the current primary down, and the new primary property's
address is copied onto the loan file. Leave isPrimary out and the
existing primary stays as it is.

Only properties is accepted here. A loan-level field sent to this
route — borrower, loan, primaryStatusId and so on — is refused
with a 422 rather than quietly dropped. Send those to
PATCH /api/v4/loans/{id} instead.

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

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

Numeric loan-file id (LMRId).

Body Params

Body for POST /api/v4/loans/{id}/properties. Only properties is accepted — loan-level fields sent here are rejected with 422 rather than silently dropped.

properties
array of objects
required
length ≥ 1

One or more properties to add. Each entry has to be an object with at least one property field in it. A bare value such as [1,2,3] or ["x"], and an empty object {}, are refused with a 422.

properties*

A property being ADDED through POST /api/v4/loans/{id}/properties — every field the shared Property shape accepts, except propertyId. The platform assigns that here, so sending one is refused with a 422.

⛔ This list is written out in full rather than composed from Property with the id subtracted. The subtraction form (allOf plus not: {}) was the only such construct in the whole v4 surface, and it broke this operation's page on readme.io — ERR-FYBC1O — while ALSO rendering propertyId in Body Params, the one field the description says is not accepted. Flat and boring is the requirement here: a published reference page has to render. The duplication is held to Property minus propertyId by tests/Unit/Files/V4/PropertyCreateSchemaTest.php, so it cannot drift.

boolean

Marks this as the primary subject property (exactly one per loan). Setting it on one property DEMOTES the previous primary — you never need to clear the old one. ⚠️ The properties array is returned PRIMARY-FIRST, so after promoting a property it moves to position 0; the order reflects primacy, not the reverse.

string | null
string | null
string | null
string | null

The property's state. ⚠️ This one is checked against your own company's settings, so the values it accepts differ from company to company, and from one loan program to the next. That is why it is not written out here as a fixed set of values: the permitted set is your configuration, not something the platform fixes.
When your company's Custom Loan Guidelines for this loan's program list the property states they allow, a state outside that list is refused with 422 VALIDATION_FAILED, and the message names the states that are allowed. The list that applies is the one for the loan program in this request (loanProgram), falling back to the program already on the loan.
Two cases are deliberately accepted, so that valid loans keep saving.
A company with no list configured is unrestricted. Every state in the platform's own state list is accepted, plus the two US territory codes GU (Guam) and V.I. (US Virgin Islands), which the property import stores even though they are not rows in that list. This is most companies, and it matches the back office, whose picker narrows only when a list exists. "Unrestricted" means no restriction from your own company — a value outside the platform's state list is still refused with 422 VALIDATION_FAILED, and the message then says the value is not a valid US state or territory code, rather than naming a company list.
Case matters here too, exactly as on the borrower state fields: FL is accepted and fl is refused. A differently-cased code is not quietly corrected, because the platform does no case conversion, and the back office's state control could not display the corrected value.
A state already saved on the property stays acceptable, even when the guidelines were narrowed afterwards. The back office does the same: it keeps offering the saved state and flags it for review rather than treating it as invalid. So a loan you fetched can always be sent back unchanged — include propertyId so the platform knows which property you mean.
Sending it blank, or null, clears the field and is never refused.

string | null
string | null
string | null
string | null
string | null
integer | null

Property type code (global master list).

number | null
number | null
integer | null
integer | null
integer | null

Whole numbers only — stored as an integer (QA F4).

integer | null

Whole numbers only — stored as an integer (QA F4).

number | null
integer | null

Owner-occupancy percentage (whole numbers only — stored as an integer).

number | null
number | null
number | null
number | null
deprecated

Deprecated — use propertyLtv. Still accepted, and means exactly what propertyLtv 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.

number | null
number | null
number | null
date | null
number | null

How much of the loan is allocated to this property. The platform totals it across the properties on the file to size the loan — that total, plus financed rehab where the loan needs it, is the file's total loan amount. Those totals are worked out when the platform calculates the loan file and shown in the back office; this API does not return them. It is also the top half of the file's loan-to-purchase, loan-to-value and qualifying loan-to-value percentages, and the basis of this property's interest-only payment. Send 0 to allocate nothing; 0 is returned as 0, so you can always tell an allocation of nothing from a property that has no figure on file.

number | null

The property's annual hazard insurance premium. Added to the flood premium to give propertyTotalHazardFloodInsurance, which the back office works out when the property is saved there (the API does not, and neither does the platform's recalculation job, BC-P15).

number | null

The property's annual flood insurance premium. Added to the hazard premium to give propertyTotalHazardFloodInsurance, which the back office works out when the property is saved there (the API does not, and neither does the platform's recalculation job, BC-P15).

number | null
deprecated

Deprecated — use propertyAnnualHoaFees. Still accepted, and means exactly what propertyAnnualHoaFees 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.

number | null

The property's annual association dues. The platform divides it by twelve and totals it across the properties for the file's monthly association-dues figure, which is shown in the back office and not returned by this API. The annual figure here is part of propertyTotalExpenses.

number | null

Total existing lien payoffs on this property. The platform totals it across the properties for the file; that total is shown in the back office and is not returned by this API. ⚠️ This is not the same figure as propertyPayOffAmount above, which is the lien release / payoff amount.

number | null

The property's monthly gross operating income — what it takes in. The platform uses it to work out this property's net operating income and its debt-service ratio, and totals it across the properties for the file; that total is shown in the back office and is not returned by this API.

integer | null

Which value this property qualifies on. 1 means its purchase price, 2 means its as-is value, and 3 means 60% of its as-is value. Send 0 to select nothing; 0 reads back as null, and a property with nothing selected contributes nothing to the file's qualifying loan amount, which the platform works out on save and shows in the back office.

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