Buy Box answers a question that comparable-property search cannot: given a property, who is most likely to buy it? You send a subject property, and the endpoint returns the investors whose past buying behavior best matches that property. It finds recent nearby sales that match your subject property, then pivots from those properties to the investors who own them. This guide covers when to reach for Buy Box, the request shape, how comp matching and investor filtering work, sorting and pagination, and billing.
When to use it
Reach for Buy Box in disposition and acquisition workflows:
You have a property to sell and want a ranked list of investors likely to buy it.
You want to know which investors are active in a specific market and asset type.
You already run comparable-property searches and want the buyer side of the same analysis.
If you only need the comparable properties themselves (not the investors behind them), use the standard Property Search comparable flow instead.
Request shape
Buy Box is a single synchronous POST. There is no job to poll and no callback.
POST https://api.batchdata.com/api/v2/investor/buybox Authorization: Bearer <your-token> Content-Type: application/json
The only required field is searchCriteria.compAddress, which identifies the subject property. Provide street plus either city and state or zip (an address hash also works). A complete request:
{
"searchCriteria": {
"compAddress": {
"street": "3741 W Evans Dr",
"city": "Phoenix",
"state": "AZ",
"zip": "85053"
},
"intel": {
"lastSoldDate": { "withinLastMonths": 12 }
},
"investor": {
"classification": { "inList": ["FLIPPER", "LANDLORD"] }
}
},
"options": {
"take": 25,
"useDistance": true,
"distanceMiles": 1,
"sort": { "field": "currentHoldings.totalPropertyCount", "sortOrder": "desc" }
}
}
Comparable-property matching controls
Buy Box first builds a pool of comparable sales near the subject property, then derives investors from that pool. The options object controls how the comps are matched:
useDistance(defaulttrue) anddistanceMiles(default1) set the search radius. The default is a one mile radius.Attribute tolerances let comps differ from the subject within a band: bedrooms (
useBedrooms, plus or minus 1), living area (useArea, plus or minus 20 percent), and year built (useYearBuilt, plus or minus 10 years) are on by default. Bathrooms, stories, exact square footage, and lot size have their own toggles and bounds.intel.lastSoldDate.withinLastMonthsrestricts comps to a rolling sale window (for example,12for the past year).
Investor filters
After the comp pool is built, Buy Box keeps the investors who pass these rules:
investor.classification(aninListfilter) defaults to["FLIPPER", "LANDLORD"]. You can narrow or widen it within the supported classifications. The two defaults describe how an investor typically makes money on a property:FLIPPER: an investor who buys a property, repairs or renovates it, and resells it relatively quickly for a profit. Flippers tend to show frequent acquisitions paired with matching dispositions over short holding periods.LANDLORD: an investor who buys a property and holds it to earn ongoing rental income. Landlords tend to show larger current holdings and fewer dispositions, since they keep properties rather than reselling them.
TRADITIONAL HOMEOWNER: an owner-occupant who buys a property to live in as their primary residence rather than to generate a return. Because Buy Box returns likely investor buyers, traditional homeowners are never returned as investors. If you includeTRADITIONAL HOMEOWNERin the classification list, the server removes it and adds a note to the responsewarningsarray explaining that it was ignored. The rest of your filter still applies.An eligibility check keeps the results to active investors: an owner must have at least three across current holdings, acquisitions, or dispositions to qualify.
You can further constrain investors by
type,currentHoldings,acquisitions, anddispositionsranges.
Sorting and pagination
options.sorttakes afieldandsortOrder. When omitted, results are sorted bycurrentHoldings.totalPropertyCountin descending order, so the largest holders come first.options.skip(default0) andoptions.take(default25, max1000) page through the ranked investors.takebounds only the returned investor count, not the size of the comp pool.
Response shape
A successful call returns the ranked investors, the comps they were drawn from, result metadata, and any advisory warnings. A trimmed example:
{
"status": { "code": 200, "text": "OK" },
"result": {
"investors": [
{
"id": "a1b2c3d4",
"name": "Evergreen Holdings LLC",
"type": "Company Owned",
"classification": ["LANDLORD"],
"currentHoldings": { "totalPropertyCount": 48 },
"acquisitions": { "totalAcquisitionCount": 12 },
"dispositions": { "totalDispositionCount": 5 },
"contacts": [
{ "name": { "first": "Dana", "last": "Reyes" }, "phones": [], "emails": [] }
]
}
],
"properties": [ { "propertyId": "P-90210-abc" } ],
"meta": {
"apiVersion": "2",
"results": { "resultCount": 25, "resultsFound": 137 },
"requestId": "req_8f2a1c"
},
"warnings": []
}
}
Each investor profile carries identity, classification, current holdings, acquisition and disposition history, mailing addresses, and contacts. meta.results.resultsFound is the total eligible investor count; resultCount is how many were returned on this page.
Billing
Buy Box is billed per matched investor profile returned, deduped within a request. The API requires take > 0, so there is no free count-only path, and because you are billed per investor returned, take is what bounds the cost of a request. You pay only for the investors that come back, so a tightly filtered search costs less than a broad one.
Buy Box is available pay-as-you-go and as part of BatchData subscription plans, with rates based on your expected volume. Contact our sales team for current pricing and to find the plan that fits your usage.