listing_ids_only: Deferred Full-Record Lookups via MLS Detail / MLS Detail Bulk

The problem this solves

Sometimes you want to decide which listings matter before paying the cost of pulling their full records — e.g. running several different MLS Search queries to build a candidate list, deduping across them, and only then fetching complete detail once per unique listing. listing_ids_only gives you the lightweight internal listing ID for every match, decoupled from the full-record fetch.

This is the MLS-side counterpart to ids_only (which returns REAPI assessorIds for public-record enrichment) — listing_ids_only returns internal listingIds for pulling full MLS records later.

Flow: MLS Search (listing_ids_only) → MLS Detail / MLS Detail Bulk

Step 1 — filter in MLS Search, get listing IDs only:

POST /v3/MLSSearch
{
  "city": "Austin",
  "state": "TX",
  "active": true,
  "has_price_changes": true,
  "listing_ids_only": true
}

Response:

{
  "data": [10637487968, 10636217225, 10636245583, ...],
  "resultCount": 340,
  "recordCount": 50,
  "resultIndex": 0
}

Paging note: same as ids_only, results are capped at 50 per response — page with resultIndex until resultIndex + recordCount >= resultCount.

Step 2 — fetch full MLS detail, one of two ways:

Single record — /v3/MLSDetail:

POST /v3/MLSDetail
{ "listing_id": 10637487968 }

Bulk (up to 1000 listing_ids per call) — /v3/MLSDetailBulk:

POST /v3/MLSDetailBulk
{
  "listing_ids": [10637487968, 10636217225, 10636245583],
  "field_sections": ["listingAgent", "listingOffice", "priceChangeHistory"]
}

MLSDetailBulk results are returned in the order you requested them. A listing_id that doesn't resolve becomes an error object at that position instead of breaking the whole batch:

{
  "data": [
    { "listingId": 10637487968, "...": "full record" },
    { "id": 999999999, "match": false, "error": true, "errorMessage": "No listing found for this listing ID." },
    { "listingId": 10636245583, "...": "full record" }
  ],
  "recordCount": 2
}

Both /v3/MLSDetail and /v3/MLSDetailBulk support the same fields/field_sections selection as MLS Search, so you can request only the sections you need on the detail pull too.

Why not just pull full records directly from Search?

You can — a plain /v3/MLSSearch call without listing_ids_only already returns full records, paged the same way. Use the two-step listing_ids_only → MLSDetailBulk flow specifically when:

• You're running multiple different searches and want to fetch full detail once per unique listing after deduping the combined ID list, instead of once per search.
• You want to persist a candidate list now (IDs are cheap to store) and defer the more expensive full-record fetch to a later stage or a different service.
• You want detail-fetch batching independent of Search's paging — MLSDetailBulk accepts up to 1000 ids in one call, vs. 50 per Search page.

If you just need "give me full records matching this one filter," skip the indirection and query /v3/MLSSearch directly.