Properties

Free-text property search

postapi.modelmatch.com/v1/properties/search

Find properties by a single free-text query — a full or partial address, an owner name, or a place. Results are ranked by relevance and tolerate typos, missing components, and reordered street directionals (e.g. "112 5th ave nw" and "112 nw 5th ave" both match). Returns the same property summary rows as the list endpoint. Use this for a search box; use the list endpoint for structured filtering.

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Body application/json

limitinteger

Max results to return (default 12).

querystringrequired

Free-text search — an address (full or partial), an owner name, or a place. Ranked by relevance; tolerates typos, missing parts, and reordered directionals.

Responses

200objectRelevance-ranked property matches

Show attributes

cursorstring

dataobject[]required

Show child attributes

absenteeOwnerboolean | null

true when the owner's mailing address (street + 5-digit zip, case/punctuation-insensitive) differs from the property's site address — a non-owner-occupied/investor signal; false when the owner mails to the property; null when either address is missing. Filterable.

activeLoanCountnumber | null

Mortgages believed to still be outstanding. IMPORTANT: 0 does not always mean the parcel is paid off — on a recently-sold parcel it usually means the buyer's new mortgage has not reached the public record yet, so the honest reading is UNKNOWN. Check activeLoanCountKnown before treating a 0 as fact, and do not infer 100% equity from it.

activeLoanCountKnownboolean

false when activeLoanCount reflects a gap in the record rather than a measurement — the parcel sold, its prior mortgage was excluded, and no replacement has been recorded yet. On those parcels activeLoanCount: 0, mortgageBalance: 0 and an equity of 100% are all consequences of the same missing document, not independent findings. To exclude them, filter preSaleLoanCount: {lte: 0} alongside activeLoanCount: {lte: 0}.

addressstring | null

apnstring | null

Assessor parcel number (cleaned)

avmobject | null

Show child attributes

confidencenumber | nullrequired

0–100

highnumber | nullrequired

lownumber | nullrequired

midnumber | nullrequired

bathsnumber | null

bedsnumber | null

borrowerStatusstring | null

borrowersobject[]

Borrowers on the current mortgage (up to two); not the owner of record.

Show child attributes

firstNamestring | nullrequired

lastNamestring | nullrequired

citystring | null

coordinatesobject | null

Show child attributes

latnumberrequired

lonnumberrequired

countyNamestring | null

County name, lowercase ("catawba county").

currentOwnerNamestring | null

The assessor's owner-of-record line as recorded — every owner on title.

equityobject | null

Show child attributes

pctnumber | nullrequired

Equity as a FRACTION of the value estimate — 1 is the whole value, 0.5 is half. A 1 alongside activeLoanCountKnown: false is arithmetic on a missing mortgage, not a free-and-clear parcel.

valuenumber | nullrequired

Estimated equity in whole dollars — the value estimate minus the outstanding balance of the mortgages we know about. It inherits their completeness: when activeLoanCountKnown is false there is no known balance to subtract, so this equals the full value estimate and should NOT be read as equity.

equityPlausibleboolean

false when equity is outside the range our equity metrics treat as possible, so aggregate equity figures exclude this parcel while this row still shows it — both are correct, they are answering different questions. Applies to pct as well, since that is value divided by the value estimate. Read alongside activeLoanCountKnown, which is the opposite failure: that one flags equity computed against a MISSING mortgage (so equity looks too GOOD), where this one flags equity distorted by an oversized one (equity looks too BAD).

fipsstring | null

FIPS county code

foreclosureobject

Show child attributes

datestring | nullrequired

Recording date of the most recent foreclosure notice (ISO 8601) — the value the foreclosureDate filter matches. Null when the parcel has no notice.

matchedbooleanrequired

scheduledAuctionDatestring | nullrequired

stagestring | nullrequired

Stage code of the most recent recorded foreclosure notice (e.g. "ND", "NS") — the value the foreclosureStage filter matches. Null when the parcel has no notice.

statusstring | nullrequired

e.g. "in_foreclosure" or "unknown"

idstringrequired

Document ID

loanCountnumber | null

Every mortgage on record for this parcel, current or not. Splits into activeLoanCount + preSaleLoanCount + the paid-off and released counts on the detail position block.

loanTypestring | null

loansobject[]

The parcel's cached top-5 loans (may be fewer than loanCount; full history is on the loans index).

Show child attributes

amountnumber | nullrequired

amountPlausibleboolean

false when amount is outside the range our mortgage metrics treat as possible, so aggregate totals exclude this loan while this row still shows it. Usually an institutional blanket loan — one note recorded against every parcel in a pool — which is a real record but not this property's debt. This judges SIZE only, so true means the amount is a believable one, not that it is the right one.

borrowerStatusstring | nullrequired

brokerNmlsstring | nullrequired

companyNamestring | null

Funding-company name as recorded on the loan.

companyNmlsstring | nullrequired

currentBalancenumber | nullrequired

interestRatenumber | nullrequired

lenderIdstring | nullrequired

Lender id for this loan — pass it back as loanLender to select every parcel financed by the same lender, exactly as a chart bucket's id round-trips. null when this loan carries no lender id; use lenderName with loanLenderName in that case.

lenderNamestring | nullrequired

Lender name as recorded on the loan document — the same value /v1/loans returns as lenderName for this loan. To filter parcels by it, pass it as loanLenderName; lenderId is the exact-id route.

lenderNmlsstring | nullrequired

loanTypestring | nullrequired

ltvnumber | nullrequired

DEPRECATED — do not use; will be removed in a future major. This is not a reliable loan-to-value ratio. It is NOT per-loan: two thirds of parcels carrying several mortgages report an identical figure across loans of very different amounts, so per-loan equity computed from it is wrong. Nor does it consistently track the parcel's combined position, so it cannot be read as a whole-parcel ratio either. null when unknown — the stored value is clipped to a fixed range and both ends mean "clipped" rather than a real ratio, so they are returned as null rather than as a plausible-looking number. For a dependable measure of borrower position use equity on the parcel.

originatorNamestring | nullrequired

originatorNmlsstring | nullrequired

recordedInterestRatenumber | nullrequired

recordingDatestring | nullrequired

transactionTypestring | nullrequired

lotSquareFeetnumber | null

mmPropertyIdstring | null

mortgageBalancenumber | null

mortgageBalancePlausibleboolean

false when mortgageBalance is outside the range our mortgage metrics treat as possible — typically a parcel carrying an institutional blanket loan, where one securitization note is recorded against every property in the pool. Sorting by mortgageBalance puts these first, so check this flag before reading the top of that list as the most heavily mortgaged homes.

ownerFirstNamestring | null

ownerLastNamestring | null

ownerMailingAddressobject | null

Primary owner's mailing address, null when none is recorded.

Show child attributes

citystring | nullrequired

statestring | nullrequired

streetstring | nullrequired

zipstring | nullrequired

ownerMiddleNamestring | null

ownerNamestring | null

ownerOccupancyenum

Assessor owner-occupancy flag, bucketed: owner_occupied (owner-occupied, incl. the vendor's phased-out non-residential code), probable_owner_occupied, or not_flagged (the assessor did not flag the parcel — not proof of an investor, but where non-owner-occupied/investor parcels land; pair with absenteeOwner). Filterable.

Options:owner_occupiedprobable_owner_occupiednot_flagged

ownerOccupiedboolean | null

true only on the assessor's confident owner-occupied code ("Y"); null = not flagged / unknown, never false. Kept for compatibility — prefer ownerOccupancy.

partialBathsnumber | null

preSaleLoanCountnumber | null

Mortgages excluded from activeLoanCount because the parcel sold after they were recorded — the seller's loan, assumed paid off at closing. Read this NEXT TO activeLoanCount, never alone: a non-zero value on a parcel that still has an active loan is the normal post-sale state and means the replacement mortgage was recorded. It is only a warning when activeLoanCount is 0, which is what activeLoanCountKnown reports.

recordedInterestRatenumber | null

Genuine recorded note rate from the most-recent loan (sparse, ~7%). See loans[] for per-loan detail.

saleCountnumber | null

salePropensityobject | null

Show child attributes

categorystring | nullrequired

Low/Medium/High

scorenumber | nullrequired

0–100

salesobject

Show child attributes

countnumber | nullrequired

firstDatestring | nullrequired

lastDatestring | nullrequired

lastPricenumber | nullrequired

scoredAtstring | null

squareFeetnumber | null

statestring | null

Two-letter state abbreviation, uppercased (stored lowercase in OS)

storiesnumber | null

yearBuiltnumber | null

zipstring | null

lenderNormalizationsobject[]

How each loanLenderName value resolved against the lender dictionary. Present when a loanLenderName filter was supplied. A matchedVia of unresolved means only the recorded lender string was matched, not the lender's whole name family.

Show child attributes

aliasCountintegerrequired

Stored lender-name variants this id expands to

displayNamestring | nullrequired

idstring | nullrequired

Canonical lender-dictionary id, or null

matchedViaenumrequired

id = the value already WAS a canonical key; alias = a stored lender name; name = matched the display/canonical name; unresolved = fell back to raw text match; degraded = the dictionary could not be consulted.

Options:idaliasnameunresolveddegraded

originalstringrequired

The value the caller sent

totalDocumentsintegerrequired

Loans the dictionary attributes to this id. A small number next to a well-known lender name means the name matched a minor entry.

totalnumberrequired

400objectValidation error

401objectUnauthorized

403objectForbidden (authenticated, but missing required context — e.g. no active organization)

404objectNot found

413objectResponse payload too large — detail endpoint capped to fit Lambda response limits

503objectSearch timed out or the cluster is overloaded — retry after `Retry-After` seconds.

curl -X POST "https://api.modelmatch.com/v1/properties/search" \
  -H "x-api-key: $MODEL_MATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "<string>",
    "limit": 50
  }'

import { createClient } from "@model-match/api";

const client = createClient({ apiKey: process.env.MODEL_MATCH_API_KEY });

const { data, error } = await client.properties.search({
  body: {
    query: "<string>",
    limit: 50
  }
});

import os
import requests

res = requests.post(
    "https://api.modelmatch.com/v1/properties/search",
    headers={"x-api-key": os.environ["MODEL_MATCH_API_KEY"]},
    json={
        "query": "<string>",
        "limit": 50
    },
)
data = res.json()

200 response

{
  "cursor": "<string>",
  "data": [
    {
      "absenteeOwner": true,
      "activeLoanCount": 123.45,
      "activeLoanCountKnown": true,
      "address": "<string>",
      "apn": "<string>",
      "avm": {
        "confidence": 123.45,
        "high": 123.45,
        "low": 123.45,
        "mid": 123.45
      },
      "baths": 123.45,
      "beds": 123.45,
      "borrowerStatus": "<string>",
      "borrowers": [
        {
          "firstName": "<string>",
          "lastName": "<string>"
        }
      ],
      "city": "<string>",
      "coordinates": {
        "lat": 123.45,
        "lon": 123.45
      },
      "countyName": "<string>",
      "currentOwnerName": "<string>",
      "equity": {
        "pct": 123.45,
        "value": 123.45
      },
      "equityPlausible": true,
      "fips": "<string>",
      "foreclosure": {
        "date": "<string>",
        "matched": true,
        "scheduledAuctionDate": "<string>",
        "stage": "<string>",
        "status": "<string>"
      },
      "id": "<string>",
      "loanCount": 123.45
    }
  ],
  "lenderNormalizations": [
    {
      "aliasCount": 123,
      "displayName": "<string>",
      "id": "<string>",
      "matchedVia": "id",
      "original": "<string>",
      "totalDocuments": 123
    }
  ],
  "total": 123.45
}