Model MatchHelp

Sales

Search sales with filters

postapi.modelmatch.com/v1/sales

Search and list individual real-estate sale transactions and active listings with filters — one row per sale/listing. Filter by location (state, county, city, zip), sale price, sale or listing date, property characteristics (beds, baths, square footage, property type), and listing status, with sorting and cursor pagination. This is the discrete per-transaction sales-record search: use it to find specific sales or build a filtered list of sold/active listings. If you only need how many sales match and not the records themselves, send the same request body to countSales.

Authorization

x-api-keystringrequired

API key or OAuth token. See Authentication.

Body application/json

advancedFiltersone of
Show child attributes
Option 1object
Show child attributes
childrenone of[]required

Array of filter expressions (AND)

Same shape as its parent.

typeenumrequired
Options:and
Option 2object
Show child attributes
childrenone of[]required

Array of filter expressions (OR)

Same shape as its parent.

typeenumrequired
Options:or
Option 3object
Show child attributes
childone ofrequired

Same shape as its parent.

typeenumrequired
Options:not
Option 4object
Show child attributes
fieldstringrequired
openumrequired

Comparison operator. exists means the field has a REAL value: on fields whose source records an unknown as an in-domain value (e.g. beds, squareFeet, lotSquareFeet, where an unrecorded measurement is stored as 0), those docs count as NOT existing. neq keeps docs with no value — it removes only what is known to equal the value, matching the reading of an exclusion.

Options:eqneqgtgteltltebetweeninmatchgeoDistanceexists
typeenumrequired
Options:filter
valuenull

Comparison value

filtersone of
Show child attributes
Option 1object
Show child attributes
childrenone of[]required

Array of filter expressions (AND)

Same shape as its parent.

typeenumrequired
Options:and
Option 2object
Show child attributes
childrenone of[]required

Array of filter expressions (OR)

Same shape as its parent.

typeenumrequired
Options:or
Option 3object
Show child attributes
childone ofrequired

Same shape as its parent.

typeenumrequired
Options:not
Option 4object
Show child attributes
fieldstringrequired
openumrequired

Comparison operator. exists means the field has a REAL value: on fields whose source records an unknown as an in-domain value (e.g. beds, squareFeet, lotSquareFeet, where an unrecorded measurement is stored as 0), those docs count as NOT existing. neq keeps docs with no value — it removes only what is known to equal the value, matching the reading of an exclusion.

Options:eqneqgtgteltltebetweeninmatchgeoDistanceexists
typeenumrequired
Options:filter
valuenull

Comparison value

flatFiltersobject
Show child attributes
bathsone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
bedsone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
catsAllowedboolean

Lease listings. true: a cats-OK token. false: No, or dogs-only.

cityone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
countyone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
dogsAllowedboolean

Lease listings. true: a dogs-OK token. false: No, or cats-only.

elementarySchoolone of | null

Elementary school name as listed, one or an array (any-of). Matched case-insensitively with the generic words (School, Elementary, Middle, High) removed, so Lago Vista Elementary School and Lago Vista Elementary select the same listings. All remaining words must appear in the stored name. The assigned school is as named on the listing record, not a boundary lookup. List the available values for an area with POST /v1/sales/analytics/chart and slice: "elementarySchool".

Show child attributes
Option 1string
Option 2string[]
fipsone of | null

5-digit county FIPS code — the exact-code escape hatch for county (which also accepts a county name).

Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
fireplaceboolean

true: the listing has a fireplace. false: it says it does not. Rows with no answer match neither value.

garageSpacesone of | null

Garage spaces (e.g. {gte: 2}). Rows with no garage count are excluded unless includeNulls: true.

Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
geoBoundsobject | null

Map viewport {north, south, east, west} in degrees: only listings inside the box. west greater than east crosses the antimeridian. Unlike geoPoint (a radius) this is the shape a map reports. Applies to list, count and analytics alike.

Show child attributes
eastnumberrequired
northnumberrequired
southnumberrequired
westnumberrequired
geoPointobject | null

Radius search — { lat, lon, radius } (e.g. radius "15mi" or "24km") — around any office on the agent's record; with locationSource office the CURRENT office, production their transactions.

Show child attributes
latnumberrequired
lonnumberrequired
radiusstringrequired
hasHoaboolean

true: the listing says it has an association, or carries a positive HOA fee. false: positive evidence of none (association flag N, or an explicit $0 fee) and no contradicting signal. A row with neither signal matches neither value.

highSchoolone of | null

High school name as listed, one or an array (any-of). Matched case-insensitively with the generic words (School, Elementary, Middle, High) removed, so Lago Vista Elementary School and Lago Vista Elementary select the same listings. All remaining words must appear in the stored name. The assigned school is as named on the listing record, not a boundary lookup. List the available values for an area with POST /v1/sales/analytics/chart and slice: "highSchool".

Show child attributes
Option 1string
Option 2string[]
hoaFeeobject | null

Monthly-equivalent HOA fee in dollars: a quarterly fee is divided by 3, an annual fee by 12, and so on, so {lte: 300} means "at most $300 a month" whatever the listing's payment frequency. Only rows with a recognized recurring frequency (monthly, quarterly, semi-annual, annual, semi-monthly, weekly) are comparable; one-time, unknown and missing frequencies are excluded. Rows with no fee are excluded unless includeNulls: true (use that to also keep homes with no HOA fee on record, or hasHoa: false). Reads the primary association only.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep rows where the field is missing (a range drops them by default). Requires a bound.

ltnumber
ltenumber
keywordstring | null

Words that must ALL appear in the listing description (public remarks), in any order, case-insensitive. Plain text: operators and punctuation (* ? " ( ) AND OR - :) are not interpreted. At most 200 characters and 12 words; empty or punctuation-only is a 400. Stemmed (granite matches granites), not fuzzy. Listing text is -supplied; see the display rules that apply to it.

listPriceone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
listingAgentone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
lotSizeSqftone of | null

Lot size in square feet (1 acre = 43,560). Rows with no lot size are excluded unless includeNulls: true.

Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
middleSchoolone of | null

Middle school name as listed, one or an array (any-of). Matched case-insensitively with the generic words (School, Elementary, Middle, High) removed, so Lago Vista Elementary School and Lago Vista Elementary select the same listings. All remaining words must appear in the stored name. The assigned school is as named on the listing record, not a boundary lookup. List the available values for an area with POST /v1/sales/analytics/chart and slice: "middleSchool".

Show child attributes
Option 1string
Option 2string[]
mlsStatusone of | null
Show child attributes
Option 1enum
Options:SLDACTPNDCancelledWDNEXPCNTOFFUNKRNTDRNTLSERNT-SLDRNT-ACTRNT-PNDRNT-WDNRNT-EXPRNT-LSERNT-RNTD
Option 2enum[]

Match any status

Options:SLDACTPNDCancelledWDNEXPCNTOFFUNKRNTDRNTLSERNT-SLDRNT-ACTRNT-PNDRNT-WDNRNT-EXPRNT-LSERNT-RNTD
Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
modeenum
Options:andor
newConstructionboolean

true: the listing is flagged new construction, or its condition says new / under construction / to be built / pre-construction. false: flagged not-new and no such condition. A row with neither signal matches neither value.

petsAllowedboolean

Lease listings (combine with propertyType: "Residential Lease"). true: cats OK, dogs OK or a plain Yes. false: No, with nothing permitting. Negotiable and detail-only values (size limit, deposit) with no OK token match neither value.

poolPrivateboolean

true: the listing has a private pool. false: it says it does not. Community pools are not distinguished (feeds record them inconsistently). Rows with no answer match neither value.

priceReducedboolean

true: the current list price is below the ORIGINAL list price. false: at or above it. Rows missing either price match neither value. (Not based on previousListPrice, which is unreliable.)

priceReductionPercentobject | null

How far the current list price is below the ORIGINAL list price, in percent of the original: {gte: 5} = cut by at least 5%. Negative means the price was raised. Rows missing either price are excluded unless includeNulls: true. Pair with priceReduced: true to exclude unchanged listings from a lte range.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep rows where the field is missing (a range drops them by default). Requires a bound.

ltnumber
ltenumber
propertyIdone of | null

Parcel id — every sale record of one property (the mmPropertyId on a loan or property record). Loans' propertyId selects the same parcel.

Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
propertyTypeone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
saleDateone of | null
Show child attributes
Option 1string

Exact date, or a whole period: YYYY-MM-DD (that day), YYYY-MM (the whole month — "2025-06" = 2025-06-01 through 2025-06-30) or YYYY (the whole year). YYYYMMDD, MM/DD/YYYY, an ISO-8601 datetime and epoch milliseconds are also accepted. An unparseable value is a 400.

Option 2object

Date range. Excludes null/missing-field docs by default; add includeNulls: true to keep them. Bounds accept YYYY, YYYY-MM, YYYY-MM-DD, YYYYMMDD, MM/DD/YYYY, a full ISO datetime or epoch milliseconds; an unparseable bound is a 400. A partial bound denotes the whole period and expands to the edge that preserves the operator: gte/lt take the period START, gt/lte take the period END — so {gte: "2024"} means on/after 2024-01-01 and {lte: "2024"} means through 2024-12-31.

Show child attributes
gtstring
gtestring
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires a bound.

ltstring
ltestring
salePriceone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
schoolDistrictone of | null

School district name, one or an array (any-of). Matched case-insensitively with the generic words removed, so Austin Independent School District, Austin ISD and AUSTIN select the same listings. Matches the district assigned at any level (elementary, middle or high). It is a name match, not a boundary lookup: Austin would also match a district named Austin Achieve, so pair it with a location filter. List the available values for an area with POST /v1/sales/analytics/chart and slice: "schoolDistrict".

Show child attributes
Option 1string
Option 2string[]
soldAgentone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
soldPriceone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
sqftone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
stateone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
storiesone of | null

Number of stories: 3, [1, 2] or {lte: 1} for single level. Where the listing has no stories value the building's story count is used instead, which for a condo is the whole building. Rows with neither are excluded unless includeNulls: true.

Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
waterfrontboolean

true: waterfront property. false: it says it is not. Rows with no answer match neither value.

yearBuiltone of | null
Show child attributes
Option 1number
Option 2number[]

Match any value

Option 3object

Numeric range. Excludes null/missing-field docs by default; add includeNulls: true to keep them.

Show child attributes
gtnumber
gtenumber
includeNullsboolean

Also keep docs where the field is null/missing (a range filter drops them by default). Requires at least one of gte/lte/gt/lt.

ltnumber
ltenumber
zipone of | null
Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
zipCodeone of | null

ZIP code. Canonical key on sales (matches loans zipCode and the response DTO); zip is an alias kept for cross-entity parity.

Show child attributes
Option 1string
Option 2string[]

Match any value

Option 3object

Fuzzy text match

Show child attributes
matchstringrequired
paginationobject
Show child attributes
cursorstring

Opaque cursor from previous response for next page

sizeinteger

Page size (1-100, default 25)

periodenum

Date window for loans / sales / market endpoints. Accepts every Period value plus rolling windows: last30Days / last60Days / last90Days (today minus 30 / 60 / 90 days through today), previousMonth (the last complete calendar month) and currentMonth (the 1st of this month through today). All windows are resolved in UTC with inclusive calendar-date bounds. Rolling windows are only accepted by the loans, sales and market endpoints (list, count, breakdowns, analytics summary / time-series / chart); originators / companies / branches / agents / offices endpoints return 400 for them.

Options:2017201820192020202120222023202420252026last3Monthslast6Monthslast12Monthslast14Monthslast16Monthslast18Monthslast24MonthsyearToDateallTimelast30Dayslast60Dayslast90DayspreviousMonthcurrentMonth
sortobject[]
Show child attributes
fieldenumrequired
Options:citystatezipCodecountysalePricesaleDatelistPricesoldPricelistingAgentsoldAgentmlsStatusbedsbathssqftyearBuiltpropertyType
orderenum
Options:ascdesc

Responses

200objectPaginated list of sales
Show attributes
cursorstring
dataobject[]required
Show child attributes
apnstring | null
bathsnumber | null

Number of full bathrooms

bedsnumber | null

Number of bedrooms

buyerNamestring | null
citystring | null
coListAgentIdstring | null

ModelMatch agent ID for the co-listing agent, same rule

coListAgentNamestring | null

Co-listing agent's name as the recorded it

coordinatesobject | null
Show child attributes
latnumberrequired
lonnumberrequired
cumulativeDaysOnMarketnumber | null

Cumulative days on market across relists, as the states it.

daysOnMarketnumber | null
fipsstring | null
idstringrequired

Document ID

lastPriceChangeDatestring | null

Date of the most recent list-price change (YYYY-MM-DD). Roughly 60% filled on active listings.

listDatestring | null

list date (YYYY-MM-DD)

listPricenumber | null

List price in dollars

listingAgentIdstring | null

ModelMatch agent ID for the listing agent — the agent the keys resolve to (the agentSales / loans rule), else the sale's linked agent id

listingAgentNamestring | null
mediaobject

The first listing photo found on the open web, how many were found, and where from. Present on a list or map row only while a non-expired found record exists for THIS listing, otherwise the key is absent. Same caveats as SaleMedia: third-party links, attribute to source.host, they can stop resolving.

Show child attributes
countintegerrequired

How many photos exist for this listing (the full list is on GET /v1/sales/{id})

coverobjectrequired
sourceobjectrequired
mlsDaysOnMarketnumber | null

Days on market as the states it for this listing. Distinct from daysOnMarket, which is only filled on some sold rows.

mlsStatusenum | null

Listing status code

Options:SLDACTPNDCancelledWDNEXPCNTOFFUNKRNTDRNTLSERNT-SLDRNT-ACTRNT-PNDRNT-WDNRNT-EXPRNT-LSERNT-RNTDnull
mmPropertyIdstring | null

Property id of the parcel this listing was matched to — the same id the propertyId filter takes. May not resolve to a parcel in some counties: in Travis, Williamson (TX), Hillsborough (FL) and Wake (NC) the id on a listing is built from the account number and usually does NOT exist as a property record, while in e.g. Maricopa, Denver and Davidson it usually does. Do not treat it as a guaranteed join key to /v1/properties.

originalListDatestring | null

Date the property was first listed (YYYY-MM-DD), which can precede listDate when it was relisted.

originalListPricenumber | null

Original list price in dollars

pendingDatestring | null

Date the listing went pending (YYYY-MM-DD). Filled on about half of sold listings and few active ones.

previousListPricenumber | null

List price before the most recent change, in dollars. Can equal listPrice (a change recorded on the list date) and is not guaranteed to be consistent with lastPriceChangeDate — verify before presenting a price-history timeline. Roughly 60% filled on active listings, about a third on sold.

propertyTypestring | null

Listing property type (e.g. Residential, Condo)

recordingDatestring | null
salePricenumber | null

Transaction price in dollars

sellerNamestring | null
soldAgentIdstring | null

ModelMatch agent ID for the sold/buying agent, same rule

soldAgentNamestring | null
soldDatestring | null

sold date (YYYY-MM-DD) — the close, which can differ from transactionDate (the recorded deed)

soldPricenumber | null

Sold price in dollars

sqftnumber | null

Living area in square feet

statestring | null
streetAddressstring | null
transactionDatestring | null
yearBuiltnumber | null

Year the property was built

zipCodestring | null
locationNormalizationsobject[]

How each location filter value resolved. Present when a city/county/state/zip filter was supplied.

Show child attributes
candidatesstring[]

Location ids matching an ambiguous name, ranked. Use instantSearch or suggestLocations to pick one.

confidenceenumrequired

"exact" — matched a dictionary entry as written. "normalized" — resolved to a different spelling or merged several candidates. "fallback" — NOT resolved; the raw value was passed through, so a zero result means the name was not recognized rather than empty.

Options:exactnormalizedfallback
displayNamestringrequired
fieldstringrequired

The filter key this applies to

idstring

Resolved location id — pass this back for an exact filter

normalizedstringrequired
originalstringrequired
variantsstring[]

Spellings actually queried against the index

totalnumberrequired
400objectValidation error. Includes unresolvable location filters: a `city`/`county`/`state`/`zip` value that does not match a recognized location returns 400 rather than an empty result set. Resolve the name with `instantSearch` (use an id from its `results.locations[]`) or `suggestLocations` (use the `id` of a `source: "dictionary"` result), then pass that id back as the filter value.
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.