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 investors who recently bought or sold comparable properties nearby. 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": "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. These options belong in options, not in searchCriteria: useDistance, distanceMiles, useBedrooms, useBathrooms, useStories, useArea, useLotSize, and useYearBuilt.

useDistance and distanceMiles (default 1) set the search radius. The default is a one mile radius. When the request does not send useDistance, it is true unless useBoundingBox is true. With useDistance set to false and no bounding box, Buy Box applies no geographic limit. To use a rectangle instead, set useDistance to false, set useBoundingBox to true, and send both boundingBoxNw and boundingBoxSe.
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.withinLastMonths restricts comps to a rolling sale window (for example, 12 for the past year).

A wider search does not always return more investors. Buy Box builds a comp pool with a fixed maximum size. When more comparable sales match than the pool can hold, Buy Box keeps only part of them. Distance and sale date do not decide which comparable sales Buy Box keeps. Because of this, a larger distanceMiles or a longer withinLastMonths can return fewer investors, and a different set of investors. To reduce this effect, set searchCriteria.investor.ownership to current. Buy Box then returns only the current owners of comparable properties that sold inside the sale window, and not the investors who only sold one.

searchCriteria.investor.ownership sets which owners of a comparable sale qualify: current (the investor owns the property now), previous (the investor sold the property), or any (both, the default). The sale window also applies with current: Buy Box returns only the current owners of comparable properties that sold inside the sale window.

Investor filters

Buy Box keeps the investors who pass these rules:

investor.classification defaults to ["FLIPPER", "LANDLORD"]. Send it as an operator object, for example { "inList": ["FLIPPER", "LANDLORD"] }. A plain array such as ["FLIPPER", "LANDLORD"] is not a supported shape: the request succeeds, but Buy Box applies no classification filter. A classification that you send replaces the default list. It does not narrow it. For example, { "equals": "CASH BUYER" } returns every cash buyer, including investors who are neither flippers nor landlords. To get cash buyers who are also flippers or landlords, send the request without classification and keep the investors whose classification includes CASH BUYER. notInList returns investors whose classifications include none of the listed values. With the default list, or with an equals, inList, or matches filter that keeps at least one value other than TRADITIONAL HOMEOWNER, every investor that Buy Box returns has at least one classification. 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 include TRADITIONAL HOMEOWNER in an equals, inList, or matches filter, the server removes it and adds a note to the result.warnings array of the response. The rest of your filter still applies. If TRADITIONAL HOMEOWNER is the only value in the list of an inList filter, no classification remains and the request returns no investors. If it is the only value of an equals or matches filter, no classification filter applies. Buy Box always excludes TRADITIONAL HOMEOWNER, so listing it in notInList changes nothing.
An eligibility check keeps the results to active investors: an owner must have at least three current holdings, three acquisitions, or three dispositions to qualify.
You can further constrain investors by type, currentHoldings, acquisitions, and dispositions ranges. These filters apply after Buy Box builds the comp pool, so they do not change which comparable sales enter the pool.

Sorting and pagination

options.sort takes a field and a sortOrder. Set field to a bare sort key such as totalPropertyCount. A dotted response path such as currentHoldings.totalPropertyCount is rejected with a 400 error. When you omit options.sort, results are sorted by current holdings (totalPropertyCount) in descending order, so the largest holders come first.
options.skip (default 0) and options.take (default 25, max 1000) page through the ranked investors. take must be an integer from 1 to 1000, and any other value is rejected with a 400 error. skip plus take must not be more than 10000, or the request is rejected with a 400 error. take bounds 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.

Each investor also has matches, matchedAsCurrentOwner, and matchedAsPreviousOwner. matches lists each comparable property that the investor matched on, with its propertyId and an ownership object (isCurrentOwner, isPreviousOwner, and currentSaleDate). matchedAsCurrentOwner is true when the investor currently owns at least one of those properties. matchedAsPreviousOwner is true when the investor sold at least one of them inside the sale window.

properties lists the comparable properties behind the matched investors, deduplicated by propertyId with at most one property per investor. This array is never longer than investors and does not list every comparable property evaluated. The two arrays are not positionally aligned: properties[i] does not correspond to investors[i].

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.

Buy Box developer guide: find likely investors for a property