Score a property address
Scores a single property address and returns a rehab-aware valuation and the maximum allowable offer — the most a flip buyer on standard financing can pay and still clear the target margin.
This is a Metered Call. The Credit cost is resolved by the Ledger inside the same transaction that records the Spend; it is never sent by the client. The Spend is committed before the scoring service is called, so a call that reaches the scoring service has already been paid for, and a call that fails before the Spend consumes nothing.
Send an Idempotency-Key to make a retry safe. A key is replayed only when the earlier call succeeded and its response was stored. If the earlier call was refunded, ended without a stored response, or is older than the replay window, the key is taken over: the new request runs and is charged, whatever body it carries. Otherwise the same key sent with a different body is refused as a conflict, and nothing is charged for it.
POST /v1/validate is the validation endpoint for this call, and it is free.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Idempotency-KeyAn opaque string of your choosing that makes retrying this request safe. Optional — a request without one is never an error, and is charged per call. Reusing a key with the same body within 24 hours returns the stored result and is not charged again, but only when the earlier call succeeded and its response was stored. Only successful responses are stored: if the earlier call was refunded or ended without a stored response, the key is taken over and the new request runs and is charged, whatever body it carries. Otherwise reusing a key with a different body is rejected as a conflict, and nothing is charged for it. The replay window is 24 hours, measured from the request that produced the stored result; after 24 hours the same key is a new request and is charged. If an identical request carrying the same key is still in flight, this one waits briefly for that result; if it does not arrive, the response is 409 with a Retry-After header and no Credits are consumed for it. Keys are scoped to your Account — one Account never replays another Account's result. POST /v1/validate ignores this header: it is not a Metered Call, so there is nothing to replay.
Score a property address › Request Body
addressThe full street address of the property to score.
conditionThe property's condition, which sets the repair budget the derived numbers are built on. Optional: omit it and the property is priced as though it needs no repairs, which is exactly what turn_key does. It is a request option rather than a second property, so sending it never changes what the call costs.
tear_down is accepted by this schema and refused by the endpoint with a 400, before any Credits are consumed. That is deliberate rather than an oversight: the scoring service has no land-value estimate, so there is no honest way to price a tear-down here. Analyse lot value separately.
Repair figures are a screening range, not a contractor bid.
rehab_budgetYour own repair budget for this property, in whole dollars. Optional, and additive: an integration that does not send it is unaffected.
When you send it, the repaired value and the maximum allowable offer are built from your figure instead of the bracket condition maps to, and the rehab_budget in the response is the number the arithmetic actually used. Sending rehab_budget and condition together is legal — rehab_budget wins, every time — so you never have to choose the bracket that comes closest to a number you already know.
condition: tear_down is still refused with a 400 even when you send a repair budget. A repair budget does not answer what a tear-down needs, which is a land value, and there is no land-value estimate behind these numbers.
Repair figures are a screening range, not a contractor bid.
target_marginThe profit margin your buyer needs, as a fraction of the repaired value — 0.2 means twenty percent. Optional, and additive: an integration that does not send it is unaffected, and is priced at the default of 0.2.
When you send it, the maximum allowable offer is solved at your margin rather than the default one. The target_margin in the response is always the margin the answer was priced at, whether you sent one or not, so "what margin is this price built on?" is answerable on every response.
The target margin is a policy figure calibrated by judgment, not a parameter fitted to a data set — which is exactly why you can override it.
Price the property as you describe it, not as the county record has it. Optional, and additive: an integration that does not send it is unaffected and its answers do not move.
Send any of the six facts below and that value is used in place of the county record's, for the model, for the comparable-sales band and for the price derived from it. Every fact in subject_property.facts says where it came from, so a value you stated reads caller-stated and everything else reads county-record — a claim can never be mistaken for a record.
A value you supply reads caller-stated even when it matches the county's own figure. The label says where the number came from, not whether it changed.
Only these six facts, and nothing else. Any other key — including latitude, longitude, partial_bathrooms, address, or a misspelling of one of the six — is refused with a 400 before any Credit is spent, rather than being ignored. The coordinates are never overridable, and that is a rule rather than an omission: a what-if changes the house's facts, never which house.
Values must be usable, and an empty overrides is refused. A value must be the right JSON type, and must satisfy the rule stated on each fact below; null is refused, because an override may state a value but never erase one. overrides: {} is refused too — it declares a what-if while stating no claim, and its answer would be indistinguishable from a call that sent no overrides at all. Every one of these is a 400 before any Credit is spent.
The required facts are still required. If the property still lacks a fact the valuation needs after your values are applied, the call is refused and the Credit is refunded, exactly as an ordinary request would be. There is no "score it anyway". Your lot_size_square_feet or property_type can supply a fact the county record was missing, in which case the call scores and that fact reads caller-stated.
Overriding bathrooms does not change partial_bathrooms, which stays at the county's figure and is not overridable. This service does not add the two together, so do not read your stated bathroom count plus a county partial count as one total.
Score a property address › Responses
The Scored Call succeeded. This was a Metered Call, so Credits were consumed from the Account's Balance, as resolved by the Ledger.
model_estimate_availableWhether the pricing model produced an estimate Investorlift Data Services was able to confirm for this property. Always present, alongside subject_property. When false, the model's estimate and its distribution are withheld from this response: they were checked against the comparable sales below and did not agree with them, and a confidently wrong valuation is worse than none. The Comp Band and the comparable sales are unaffected — they are derived from the sales themselves — and this call is charged as normal, because it still carries a valuation.
The property this answer is about, and the facts the valuation actually ran on. Always present on a scored answer, including one where the model's estimate was withheld. It is here so a mis-resolved address or a thin county record is visible before you act on the numbers: check that the address and the facts below describe the house you meant.
Every fact carries where it came from. county-record means the property data service's stored value for this property; caller-stated means a value you supplied in its place. Those are the only two values. A fact reads caller-stated when you supplied it through the overrides request option, and county-record otherwise — including partial_bathrooms, which cannot be overridden. A value you supply reads caller-stated even when it matches the county record's own figure.
A fact that is missing is missing on purpose. When the county record does not carry a usable value for something, that fact is left out of facts entirely rather than returned as null, 0 or an empty string. Absence is information: the valuation ran without it too. A recorded living area of zero is treated as no living area, not as a house that measures nothing.
This block is additive. It was added without changing any other member, and an integration that ignores it is unaffected.
pricing_model_arv_estimateThe pricing model's after-repair-value estimate for this property, rounded to the nearest thousand dollars. Read from the model's own value distribution rather than from the comparable sales, so it does not move when comparable sales are added or removed — the Comp Band is the number that does. Absent when model_estimate_available is false.
The predicted value distribution for this property, as quantile level to predicted value. The full distribution is returned rather than a single number: where the scoring service exposes its uncertainty, Investorlift Data Services surfaces it rather than hiding it. Absent when model_estimate_available is false.
valuation_meanThe predicted value for this property as a single point estimate. Optional: the scoring service does not always produce one, and its absence does not make the distribution above any less complete. Absent when model_estimate_available is false.
effective_sample_sizeHow much comparable evidence supported the model's estimate. A low value means the distribution above rests on thin evidence and should be read with more caution. Absent when model_estimate_available is false, because it describes an estimate that was withheld.
The Comp Band: the value range implied by the comparable sales below, size-normalised to this property where their square footage allows it. This is the number derived from recorded sales rather than from a model. Absent when too few comparable sales carried a usable price to state a range honestly — a range built on one or two sales reads as high confidence over the thinnest possible evidence.
rehab_budgetThe repair budget the numbers below were built on, in whole dollars — the figure the arithmetic actually used. When you sent a rehab_budget, this is your number. When you did not, it is the whole-project midpoint for the condition you submitted, and zero when you sent no condition, which is the same as sending turn_key. A bracket figure is a screening range reduced to a single number, not a contractor bid: small homes skew high per square foot, and the heavier brackets are the least reliable in the set. Sending your own budget replaces that estimate with your own.
rehab_adjusted_arvThe after-repair value this deal is priced against, in whole dollars: the Comp Band's middle value lifted toward its upper end in proportion to the repair budget, because a heavier renovation signals a higher-finish result. It equals the middle of the Comp Band when there is no repair signal and never exceeds the upper end, so the number stays anchored to sales that actually happened. It is derived from the comparable sales rather than from the model, so it moves when the comparable sales do. The thresholds that shape the lift are policy figures calibrated by judgment, not fitted parameters. Absent whenever the Comp Band is absent.
target_marginThe profit margin the maximum allowable offer (max_allowable_offer, below) was solved at, as a fraction of rehab_adjusted_arv — 0.2 means twenty percent. Always present on a priced answer, whether or not you sent a target_margin: when you sent one it is your figure, and when you did not it is the default this service priced at. It is published either way so that "what margin is this price built on?" is answerable on every response rather than only on the ones that named it. The default is a policy figure calibrated by judgment, not a fitted parameter. Absent whenever the Comp Band is absent.
The maximum allowable offer (MAO): the highest purchase price at which a cash flip buyer on standard financing still clears the target margin. It is the algebraic inverse of a flip pro forma rather than a price quantile, so a seller's suggested price and a buyer's underwriting agree by construction.
This is the investor's ceiling — your offer to the seller is this minus your fee.
It is not a prediction of what the property will trade at. The financing figures behind it — down payment, interest, points, closing costs, hold period and target margin — are policy figures calibrated by judgment and intended to be tuned; they are not fitted to any data set. Absent whenever the Comp Band is absent.
The line items behind the maximum allowable offer — the deal as the flip buyer it is solved for would carry it. Present on exactly the same answers max_allowable_offer is present on, and absent whenever the Comp Band is absent.
These numbers are whole dollars, and down_payment plus loan is the maximum allowable offer exactly. Rounding is applied once, above both the price and these lines, so the figures you read here are the figures that add up — there is never a rounded total that disagrees with its own rounded parts. That identity holds on every answer, including the ones where no price could be solved.
When a price was solved — max_allowable_offer.clamped is false — the whole stack reconciles. Add down_payment, loan, rehab_budget, interest, points, closing_costs and target_profit and you land back at rehab_adjusted_arv. The gap is rounding and nothing else — the price to the nearest thousand, rehab_adjusted_arv to the nearest thousand, and each remaining line to the nearest dollar — so it stays a little over a thousand dollars across the repair budgets this API brackets, and grows with a very large repair budget because a longer hold puts more financing cost on each rounded dollar of price.
When clamped is true there is nothing to reconcile. No price in range cleared the target margin, so the published price is a floor rather than a solution; the lines still describe that published price, but they will not add back to rehab_adjusted_arv and the difference can be large. Read clamped first on those answers.
Every figure here follows from the financing assumptions behind the maximum allowable offer, which are policy figures calibrated by judgment and intended to be tuned — not a quote from any lender, and not fitted to a data set.
A price-per-square-foot range taken over the comparable sales listed in comps, stated as evidence beside comp_band rather than as part of the valuation. It feeds nothing: no other member of this response is computed from it. Read basis to learn which sales it covers. It is present whenever at least one comparable sale carries both a usable sale price and a usable square footage, INCLUDING on answers where the model estimate was withheld (model_estimate_available: false), because it is computed from the comparable sales rather than from the model. It is absent when no comparable sale carries both. No member of it is ever null.
The comparable sales the Comp Band was derived from, in the order the scoring service ranked them, as stored by the property data service. The property's own prior sale is removed before anything is computed. Absent when the scoring service returned none.
Score a batch of property addresses
Scores up to the documented batch limit of properties in one request and returns one answer per property, in submission order.
Each answer carries the core numbers only. A batch entry is the same answer POST /v1/predict returns for that property, minus the list of comparable sales: the Comp Band, the qualifying count, the price-per-square-foot range and every derived figure are all here, but the individual sales behind them are not. To see them, score that property on its own with POST /v1/predict, by address: a Scored Call identifies a property by address only, and property_id is not one of the members it accepts.
This is a Metered Call: Credits are charged per property submitted, and the Credit cost is resolved by the Ledger inside the same transaction that records the Spend — it is never sent by the client. The Spend for the whole batch is committed before any property is scored, so the cost of a batch is known and paid in full before any work begins. A batch the Account's Balance cannot afford is rejected in full — never partially: nothing is charged, nothing is split, and the request can be retried unchanged after a top-up.
Credits are charged per property submitted, and refunded per property that fails for a reason the refund policy covers. A property that fails for one of the covered reasons does not stop the ones after it: its share of the batch's Credits is returned to the Account as its own Refund, and every property after it is still attempted. The response is still 200, and the failed property's entry in results is the same error object a single call would have returned for it — so an integration branching on type needs no second contract. A refusal outside those reasons stops the batch instead: the properties after it are not attempted, no results array is returned, the whole request answers 503 spend-indeterminate, and every Credit recorded for the batch is returned to the Account as a Refund. The Account is charged for every property that produced an answer and for nothing else.
Send an Idempotency-Key to make a retry safe. Keys behave exactly as on POST /v1/predict, and the same body sent to both endpoints under one key is a conflict, never a replay.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Idempotency-KeyAn opaque string of your choosing that makes retrying this request safe. Optional — a request without one is never an error, and is charged per call. Reusing a key with the same body within 24 hours returns the stored result and is not charged again, but only when the earlier call succeeded and its response was stored. Only successful responses are stored: if the earlier call was refunded or ended without a stored response, the key is taken over and the new request runs and is charged, whatever body it carries. Otherwise reusing a key with a different body is rejected as a conflict, and nothing is charged for it. The replay window is 24 hours, measured from the request that produced the stored result; after 24 hours the same key is a new request and is charged. If an identical request carrying the same key is still in flight, this one waits briefly for that result; if it does not arrive, the response is 409 with a Retry-After header and no Credits are consumed for it. Keys are scoped to your Account — one Account never replays another Account's result. POST /v1/validate ignores this header: it is not a Metered Call, so there is nothing to replay.
Score a batch of property addresses › Request Body
The properties to score, each the same shape POST /v1/predict accepts. Order is preserved: the response's results array answers these properties in this order. Duplicate addresses are allowed and each is charged — two identical entries are two work items.
Score a batch of property addresses › Responses
The batch was processed. This was a Metered Call, so Credits were consumed from the Account's Balance as resolved by the Ledger, and any property that failed for a reason the refund policy covers has had its share returned as a Refund. Individual properties may have failed — each entry in results says which.
One entry per submitted property, in submission order. Entry i answers submitted property i: the position is how a failing property is identified, and no index is interpolated into any message.
Check a request without spending
Checks that a request body would be accepted by POST /v1/predict, and returns a verdict.
This endpoint is free. It consumes no Credits and never calls the scoring service, so it keeps working at a zero Balance. With an API Key it makes no Ledger call of any kind, so it also answers during a Ledger outage. A connected app — one that signed you in instead of holding an API Key — makes one Ledger read here to confirm the connection is still approved, so while that read is failing it answers 503 call-not-started. Nothing is charged either way. It requires a valid credential — an API Key, or an account sign-in — and nothing else.
Any Idempotency-Key header sent to this endpoint is ignored. There is no Spend to make idempotent, so no claim is recorded and no key is stored.
A verdict of false is returned only for a body this endpoint can judge on its own — shape, required fields and the property cap. The scoring service remains the authority on whether a well-formed address can actually be scored.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Check a request without spending › Request Body
addressThe full street address of the property to score.
conditionThe property's condition, which sets the repair budget the derived numbers are built on. Optional: omit it and the property is priced as though it needs no repairs, which is exactly what turn_key does. It is a request option rather than a second property, so sending it never changes what the call costs.
tear_down is accepted by this schema and refused by the endpoint with a 400, before any Credits are consumed. That is deliberate rather than an oversight: the scoring service has no land-value estimate, so there is no honest way to price a tear-down here. Analyse lot value separately.
Repair figures are a screening range, not a contractor bid.
rehab_budgetYour own repair budget for this property, in whole dollars. Optional, and additive: an integration that does not send it is unaffected.
When you send it, the repaired value and the maximum allowable offer are built from your figure instead of the bracket condition maps to, and the rehab_budget in the response is the number the arithmetic actually used. Sending rehab_budget and condition together is legal — rehab_budget wins, every time — so you never have to choose the bracket that comes closest to a number you already know.
condition: tear_down is still refused with a 400 even when you send a repair budget. A repair budget does not answer what a tear-down needs, which is a land value, and there is no land-value estimate behind these numbers.
Repair figures are a screening range, not a contractor bid.
target_marginThe profit margin your buyer needs, as a fraction of the repaired value — 0.2 means twenty percent. Optional, and additive: an integration that does not send it is unaffected, and is priced at the default of 0.2.
When you send it, the maximum allowable offer is solved at your margin rather than the default one. The target_margin in the response is always the margin the answer was priced at, whether you sent one or not, so "what margin is this price built on?" is answerable on every response.
The target margin is a policy figure calibrated by judgment, not a parameter fitted to a data set — which is exactly why you can override it.
Price the property as you describe it, not as the county record has it. Optional, and additive: an integration that does not send it is unaffected and its answers do not move.
Send any of the six facts below and that value is used in place of the county record's, for the model, for the comparable-sales band and for the price derived from it. Every fact in subject_property.facts says where it came from, so a value you stated reads caller-stated and everything else reads county-record — a claim can never be mistaken for a record.
A value you supply reads caller-stated even when it matches the county's own figure. The label says where the number came from, not whether it changed.
Only these six facts, and nothing else. Any other key — including latitude, longitude, partial_bathrooms, address, or a misspelling of one of the six — is refused with a 400 before any Credit is spent, rather than being ignored. The coordinates are never overridable, and that is a rule rather than an omission: a what-if changes the house's facts, never which house.
Values must be usable, and an empty overrides is refused. A value must be the right JSON type, and must satisfy the rule stated on each fact below; null is refused, because an override may state a value but never erase one. overrides: {} is refused too — it declares a what-if while stating no claim, and its answer would be indistinguishable from a call that sent no overrides at all. Every one of these is a 400 before any Credit is spent.
The required facts are still required. If the property still lacks a fact the valuation needs after your values are applied, the call is refused and the Credit is refunded, exactly as an ordinary request would be. There is no "score it anyway". Your lot_size_square_feet or property_type can supply a fact the county record was missing, in which case the call scores and that fact reads caller-stated.
Overriding bathrooms does not change partial_bathrooms, which stays at the county's figure and is not overridable. This service does not add the two together, so do not read your stated bathroom count plus a county partial count as one total.
Check a request without spending › Responses
The request body was checked. No Credits were consumed.
validWhether this body would be accepted by POST /v1/predict. Always true on a 200 — a body that would be rejected returns the same 400 or 413 the Metered Call returns.