When you build a Property Search request, each text field accepts a small grammar of operators that tell the API how to match your value. Choosing the right operator is the single biggest factor in how fast your search returns and how relevant your results are. This guide walks through every operator, when to use it, and the patterns that produce predictable performance.

The Most Important Rule: Prefer equals When You Can

When you know the exact value you are looking for, use equals. It is the fastest operator and the most precise.

A surprising number of slow searches come from customers reaching for contains when equals would have returned the same result. contains is a wildcard search — it asks the API to scan every value in the index for a match anywhere inside the string. equals asks the index a single, direct question.

Rule of thumb:

If you have a full, known value (a complete city name, a complete subdivision name, an exact owner name) → use equals.
If you only have a fragment of the value → consider whether one of the list operators (inList, notInList) would work first, and only fall back to contains when you genuinely need substring matching.

Subdivision Searches: When and How to Use legal.subdivisionName

legal.subdivisionName supports two related use cases, and both are exact-match by design — which is why the field accepts only equals, inList, and notInList, not the wildcard operators (contains, startsWith, endsWith).

Use case 1: Property search restricted to a specific subdivision

When you have one or more known subdivision names and want every property in them, use legal.subdivisionName as a filter on a standard Property Search call. This is the right pattern for marketing list build-outs, portfolio audits, and any workflow where the subdivision is part of the search criteria — independent of any subject property.

A Property Search payload filtered to a single subdivision:

{
  "searchCriteria": {
    "address": {
      "city": {
        "equals": "Phoenix"
      },
      "state": {
        "equals": "AZ"
      }
    },
    "legal": {
      "subdivisionName": {
        "equals": "Briarwood Estates"
      }
    }
  },
  "options": {
    "skip": 0,
    "take": 25
  }
}

Use inList to span a set of subdivisions, or notInList to exclude specific ones:

{
  "searchCriteria": {
    "legal": {
      "subdivisionName": {
        "inList": [
          "Briarwood Estates",
          "Briarwood North",
          "Briarwood Heights"
        ]
      }
    }
  }
}

If you only have a fragment of a subdivision name and need to discover the full value, identify any property you know to be in the subdivision — an address you have on file, an existing customer property, or any other known parcel — and call Property Lookup on it. The response's legal.subdivisionName is the exact string to use in your equals or inList filter.

Use case 2: Comparable property search constrained to the subject's subdivision

A property comparable search returns properties similar to a subject property — matched on distance from the subject's address (compAddress), property characteristics (bedrooms, bathrooms, square footage, year built), and recent sale activity. For valuation and investment workflows, "similar" almost always has to mean "in the same subdivision." Subdivisions are stable, market-meaningful boundaries: two homes a few hundred feet apart but in different subdivisions can sit in different school zones, be served by different HOAs, and trade at materially different prices.

A comparable search has two parts that go in different places in the request body:

searchCriteria holds the subject property (compAddress) plus any explicit filters you want to apply to the result set, such as general.propertyTypeCategory.
options holds the comparable-algorithm tuning knobs: useDistance + distanceMiles, useBedrooms + minBedrooms / maxBedrooms, useBathrooms, useArea, useYearBuilt, useLotSize, useSubdivision. The min* / max* values are deltas from the subject (for example, the default minBedrooms: -1 and maxBedrooms: 1 returns comparables with one fewer to one more bedroom than the subject).

The simplest way to constrain comparables to the subject's own subdivision is options.useSubdivision: true. The comparable algorithm derives the subdivision from compAddress automatically — no separate Property Lookup step needed:

{
  "searchCriteria": {
    "compAddress": {
      "street": "8421 N Briar Ridge Way",
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85020"
    },
    "general": {
      "propertyTypeCategory": {
        "inList": [
          "Residential"
        ]
      }
    }
  },
  "options": {
    "aggComparablesMetrics": true,
    "dateFormat": "iso-date",
    "skip": 0,
    "take": 25,
    "useDistance": true,
    "distanceMiles": 1,
    "useBedrooms": true,
    "useBathrooms": true,
    "useSubdivision": true
  }
}

If you need comparables in a different subdivision than the subject's — or want inList to span multiple adjacent subdivisions — replace useSubdivision: true with an explicit legal.subdivisionName clause in searchCriteria. The two controls AND together: setting useSubdivision: true alongside a conflicting explicit equals returns zero results, because the algorithm requires the subject's subdivision and the filter requires the other one.

{
  "searchCriteria": {
    "compAddress": {
      "street": "8421 N Briar Ridge Way",
      "city": "Phoenix",
      "state": "AZ",
      "zip": "85020"
    },
    "legal": {
      "subdivisionName": {
        "inList": [
          "Briarwood North",
          "Briarwood Heights"
        ]
      }
    },
    "general": {
      "propertyTypeCategory": {
        "inList": [
          "Residential"
        ]
      }
    }
  },
  "options": {
    "useDistance": true,
    "distanceMiles": 1,
    "useBedrooms": true
  }
}

Why wildcard operators are not supported on subdivisionName

contains would seem useful if you only remember part of a subdivision name. In practice, it is the wrong tool for this field:

Subdivision names are stable identifiers, not keywords. Two subdivisions might both contain the word "Briar" but represent entirely different developments with no shared market behavior. Substring matching conflates them.
Wildcard scans on this field force index-wide reads. A contains query is implemented as *value*, which the search index cannot satisfy with a direct lookup. The cost grows with the size of the dataset, not with the size of the result set.

If you only know part of a subdivision name, use the Property Lookup approach from Use Case 1 to retrieve the full name first, then use it in equals or inList.

The Full Text-Search Grammar

Property Search supports seven text operators. They fall into three groups: single-value matches, list matches, and pattern matches.

Single-Value Operators

equals (string)

Exact match against the field value. Fast and precise. Use this whenever you know the complete value.

{
  "address": {
    "city": {
      "equals": "Phoenix"
    }
  }
}

contains (string)

Wildcard match — returns results where the field contains the value anywhere inside it. This is a substring scan and is significantly slower than equals. Use it only when you genuinely need partial matching and no other operator fits.

{
  "demographics": {
    "keywords": {
      "contains": "waterfront"
    }
  }
}

startsWith (string)

Prefix match — returns results where the field begins with the value. Faster than contains because the API can use the index to jump directly to candidates.

{
  "address": {
    "street": {
      "startsWith": "100 Main"
    }
  }
}

endsWith (string)

Suffix match — returns results where the field ends with the value. Like contains, this requires scanning every value in the index and is slower than equals or startsWith. Use sparingly.

{
  "address": {
    "zip": {
      "endsWith": "01"
    }
  }
}

List Operators

inList (array of strings, maximum 10,000)

Returns results that match any value in the list. This is the right tool when you have a set of known values — much more efficient than chaining many equals calls and clearer than a contains against a partial string.

{
  "address": {
    "city": {
      "inList": [
        "Phoenix",
        "Mesa",
        "Tempe",
        "Scottsdale"
      ]
    }
  }
}

notInList (array of strings, maximum 10,000)

Returns results that match none of the values in the list. Useful for excluding known categories (for example, excluding specific property types or specific cities from a regional search).

{
  "general": {
    "propertyType": {
      "notInList": [
        "Vacant Land",
        "Mobile Home"
      ]
    }
  }
}

Pattern Operator

matches (array of strings, maximum 10,000)

Returns results where the field matches all of the values in the array. Only applicable to string-array fields, and not supported for property loan type. Use this when a field holds multiple tags and you need every requested tag to be present.

{
  "demographics": {
    "tags": {
      "matches": [
        "pool",
        "garage",
        "single-family"
      ]
    }
  }
}

Performance Quick Reference

Operator	Index-friendly	Notes
`equals`	Yes	Fastest. Always prefer when the full value is known.
`startsWith`	Yes	Fast prefix scan.
`inList`	Yes	Fast — equivalent to many `equals` lookups.
`notInList`	Yes	Fast — negation of a list.
`matches`	Yes	Limited to string-array fields.
`endsWith`	No	Slower — requires scanning all values.
`contains`	No	Slowest — wildcard scan over every value.

Field-Specific Restrictions

Not every operator is available on every field. The restriction that most often surprises developers is on legal.subdivisionName, which supports only equals, inList, and notInList. See the dedicated section above on subdivision searches for the full rationale and the comparable-search workflow this restriction is designed around.

The Property Search API Reference lists the full set of supported operators per field. If you send an unsupported operator, the API will return a validation error explaining which operators are allowed.

Practical Patterns

Looking up properties in a known set of cities:

"address": {
  "city": {
    "inList": [
      "Phoenix",
      "Tempe"
    ]
  }
}

Looking up properties in a specific subdivision:

"legal": {
  "subdivisionName": {
    "equals": "Briarwood Estates"
  }
}

Excluding land and mobile-home property types from a regional search:

"general": {
  "propertyType": {
    "notInList": [
      "Vacant Land",
      "Mobile Home"
    ]
  }
}

Searching for property listings with a specific street prefix:

"address": {
  "street": {
    "startsWith": "100 Main"
  }
}

Summary

Reach for equals first. It is faster and more precise.
Use inList and notInList for known sets of values instead of stringing multiple operators together.
Treat contains and endsWith as last-resort operators — they scan the full index and are noticeably slower at scale.
Check the Property Search API reference for the operators allowed on each field. Not every operator is supported everywhere.