Field Selection — `fields` & `field_sections`

Why this matters

A full v3 MLS record includes every section — address, listingDetails, listingAgent, listingOffice, media, priceChangeHistory, statusChangeHistory, schools, hoa, openHouses, dataAssumptions, and more. If your application only needs price, beds, and baths, pulling the whole record wastes bandwidth and slows down every request in your pipeline — especially at scale (bulk lookups, high-QPS search, mobile clients).

fields and field_sections let you ask for exactly what you need. Smaller payload → faster serialization → faster transfer → faster time-to-render.

`fields` — pick exact paths

An array of dot-paths into the record. Supports both leaf fields and whole sub-objects.

{
  "city": "Austin",
  "state": "TX",
  "fields": ["listingPrice", "listingDetails.beds", "listingDetails.baths", "listingAgent"]
}

This returns listingPrice (a root scalar), two leaves under listingDetails, and the entire listingAgent object — nothing else.

Selecting a parent path ("listingAgent") returns everything under it.
Selecting a leaf ("listingDetails.beds") returns only that field.
Unknown paths return a 400 with a "did you mean" suggestion (leaf-aware, so "beds" alone suggests "listingDetails.beds", not an unrelated field that happens to be alphabetically close).

`field_sections` — pick whole sections by name

A shorthand for grabbing entire record sections without spelling out dot-paths:

{
  "city": "Austin",
  "state": "TX",
  "field_sections": ["listingAgent", "listingOffice", "priceChangeHistory"]
}

Valid section names: ROOT (all root-level scalars), address, agentRemarks, colistingAgent, colistingOffice, cosellingAgent, cosellingOffice, dataAssumptions, hoa, linkedListings, listingAgent, listingDetails, listingOffice, media, miscellaneous, openHouses, pastListings, priceChangeHistory, schools, sellingAgent, sellingOffice, statusChangeHistory.

An unrecognized section name 400s with a suggestion (e.g. "adress" → "address").

Using both together

fields and field_sections combine — you're not forced to choose one. The response is the union of both, deduplicated:

{
  "field_sections": ["listingAgent"],
  "fields": ["priceChangeHistory.numberOfPriceChanges"]
}

returns the full listingAgent object plus that one price-change field. If a fields entry is already covered by a section you selected, you'll get a non-fatal warning telling you it was redundant — not an error.

What's always returned

Regardless of selection, every record always includes these identity fields so results stay traceable:

listingId, assessorId, mlsNumber, mlsBoardCode, mlsBoardName, currentStatus, listingContractDate

The `public` block is separate

The public.* (public-record) block is opt-in and gated by your plan independent of field selection. Selecting public or public.* via fields doesn't bypass the entitlement check — it only requests it. See the plan/billing docs for public-record access.

When to use which

Use case	Recommendation
You need 2–5 specific values (map pins, list views)	`fields` with leaf paths — smallest payload
You need one or two whole sections (agent contact card, price history panel)	`field_sections`
You need most of the record but want to drop one heavy section (e.g. `media`)	Skip selection entirely and use `exclude`-style filtering upstream, or just accept the full record — selection is additive, not subtractive
No selection provided	Full record, every section (except `public`, which stays opt-in)

Field Selection — fields & field_sections