Check a property's history
Read one property's recorded sales, detected flips, ownership, permits and listing changes.
Choose the property
Send exactly one of address or property_id to POST /v1/history.
Both or neither returns 400 before charging.
Member presence counts: an empty address alongside property_id still means both.
An address resolves the property using the same matching, ambiguity and coverage rules as underwriting.
A property_id reads the known property directly, without address matching.
Take that identifier from an underwritten subject or comparable property; single-property underwriting accepts an address or property identifier.
Check subject_property to confirm the returned house.
For identifier lookup, address_quality.code is identified-by-property-id.
The house number and ZIP code were not compared on that path.
No other inputs are accepted.
Underwriting options condition, rehab_budget, target_margin and overrides are rejected.
Send the request
Save your API key, the credential identifying you, in INVESTORLIFT_API_KEY.
Set your client timeout to at least 30 seconds.
These examples use the address input.
Charges and empty records
This is a charged call, an API request with a price. Each successful history call is charged the price on its reference page and in the per-call price list.
A property with nothing on file is a charged answer.
When available county records contain no transactions, the call returns 200 with an empty transactions array.
Its records_statement says the records were checked and nothing was on file.
Unread or incomplete transaction records are a failure, not an empty history. The call returns a 5xx and the charge is returned to your balance.
Read the answer
Show the full response (159 lines)
Full response
The response contains subject_property, records_statement, transactions, flips, seller_position, permits, market_status and summary only.
The reference describes each member.
Transactions
transactions lists recorded events newest first.
A missing date or price is null and does not remove the event.
Events without sale_date appear last; they are not identified as the oldest.
The kind is standard-sale, foreclosure, bank-repo, family-transfer, new-construction or unknown.
The buyer_type is individual, company, trust or unknown.
These categories are derived conclusions from documents, not facts asserted by the county.
Treat unknown as not established.
A nominal-price transfer is never a standard-sale.
price_is_estimated: true means the record's own estimate, not recorded consideration.
Flips
flips lists buy/sell pairs with 540 days or fewer between recorded sale dates.
The boundary is inclusive: a hold of exactly 540 days is a flip.
Both legs need real market prices; family transfers are excluded.
days_held can be zero for a same-day close.
percentage_gain can be negative; 0.4195 means a 41.95% gain.
seller_posture is professional, private or unknown.
A company or trust is professional; an individual is private.
An unrecorded seller is unknown, not automatically private.
Ownership and loans
seller_position.owned_since uses the newest dated transaction.
seller_position.days_owned is whole days since that date.
Unestablished ownership length or a future sale date gives null, not a negative duration.
recorded_loan_available is false: no per-property loan, mortgage or lien record is available here.
There is no payoff or equity estimate.
Missing loan records do not establish free-and-clear ownership or a cash purchase.
An estimate from a loan recorded at the last sale would miss later refinances. It would need a range, not a single figure. Ownership length comes from the transaction chapter.
Permits
Read coverage_known, not the array length.
It is true only when at least one permit record was returned.
Empty records cannot distinguish no permits, unavailable county records or a nonexistent property.
Unavailable or failed permit lookups return an empty permits array, coverage_known: false and a plain statement.
The status facts are null; these records never establish that the property has no permits.
A failed permit lookup leaves the other history chapters intact, and the successful call is still charged.
The list selects the most recent permit in each category, plus every open permit and every demolition.
Categories are roof, hvac, water_heater, electrical, plumbing and demolition.
Each category has most_recent_date, most_recent_job_value and work_status; missing values are null.
Each permit has recorded dates, job_value, tags and construction_duration.
Missing dates or values are null; tags are fixed categories, not county free text.
construction_duration has no established unit; do not assume days or weeks.
work_status is completed, inactive, open, in-review or unknown.
Unknown status does not mean completed work.
has_open_permit is true for open or in-review work.
It is false only when records were retrieved and every status was readable.
Unavailable records or any unreadable status give null when no open work is established.
No permit number or reference identifier is returned, because either could retrieve a public record naming the applicant. No permit count is returned: the underlying count is a page size, not a total.
Listing changes
market_status describes the current listing.
A rental is not a sale listing: rental_listing marks it, and sale-specific dates, prices and days on market are withheld.
Unknown status remains unknown; a cancelled listing is not reported as failed.
price_reduced is true only when the low asking price was recorded after the high price.
A low price recorded first means the price went up.
If either price or either date is missing, the result is null.
Summary
summary is computed from the chapters, not a second read of the records.
Its members are booleans, fixed categories or null, with no free text.
Map these values to your own fields or decision rules.
A value not established by its chapter is null or unknown, never false.
false means checked and no.
Unavailable permit records leave open_permit_work and demolition_recorded as null.
long_tenured_owner uses the configured ownership-duration threshold.
It is null when ownership length cannot be established.
Names and identifiers
This history response omits buyer, seller and owner names, their mailing addresses and recorder document numbers. It publishes derived categories instead.
Errors and safe retries
The Trace ID, the identifier for a call, is in every response's trace-id header.
Quote it when contacting support.
property-not-found returns 422 when no record matches the identifier; the charge is returned to your balance.
History never returns unscorable-address, because it does not underwrite the property.
Send an Idempotency-Key to replay a stored successful answer without another charge.
Refunded calls or calls without a stored answer run again; the replay window also matters.
Retry safely explains each case.
Reusing a stored history key and body for /v1/predict is a conflict, not a replay.
The endpoints answer different questions.