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.

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

Historically, many slow searches came from customers reaching for contains when equals would have returned the same result; today most text fields reject contains outright. 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:

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

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:

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

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.

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:

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:

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.

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

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.

Property Search supports eight text operators. Seven are general-purpose and fall into three groups: single-value operators, list operators, and the complete-value operator. The eighth, containsWords, is specific to current-owner name search on owner.firstName and owner.lastName; it is described under Owner-Name Operator below, with the full workflow in Searching by owner name. It is not available on any other name field, including previous-owner search.

equals (string)

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

contains (string)

Wildcard match that returns results where the field contains the value anywhere inside it. This is a substring scan and is significantly slower than equals.

contains is not supported on the high and medium cardinality Property Search text fields (owner names and owner mailing fields, address and location fields, subdivision name, APN, tax id, property id, address hashes, zoning code, permit tags, and the demographics text field). See Field-Specific Restrictions for the exact list. Sending it on one of those fields returns an HTTP 400 error naming the field and operator, with guidance on the supported operators for that field. It remains available only on the low-cardinality enumerated fields (for example address.state, address.zip, general.propertyTypeCategory, general.propertyTypeDetail, and most other status and type enums).

startsWith (string)

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

Like contains, startsWith returns an HTTP 400 error on the restricted text fields listed above and is available only on the low-cardinality enumerated fields.

endsWith (string)

Suffix match that 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.

As with contains and startsWith, endsWith returns an HTTP 400 error on the restricted text fields and is available only on the low-cardinality enumerated fields.

inList (array of strings)

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.

notInList (array of strings)

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).

matches (array of strings)

Each value must be a complete stored value. matches is not a keyword, prefix, or partial search: a fragment of a longer stored value returns nothing.

Use matches with a single value, where it behaves like equals, and use inList to match any of several values.

What supplying more than one value to matches does varies by field, so do not rely on it. Matching is case-insensitive. matches is not supported for property loan type (the openLien loan-type fields).

containsWords (string, current-owner name fields only)

Tokenized, order-insensitive, case-insensitive word match, available on owner.firstName and owner.lastName only. It is not accepted on previousOwner.fullName; see Searching by previous owner. Unlike contains (a substring scan), containsWords matches whole name tokens in any order, so you can find a property by its owner's name without knowing the stored name format or the order its parts appear in. When you supply both owner.firstName and owner.lastName with containsWords, both names must appear on the same owner record. A supplied name part is matched against the whole of the owner's stored name rather than against one name component, so owner.firstName and owner.lastName are interchangeable when both are supplied. This is the supported way to search by owner name. If you use containsWords for one name and equals or inList for the other, the API checks each name separately, so the two names can match two different owners. See Searching by owner name for the full workflow.

Supply exactly one operator per field. If a field carries more than one operator, the API applies one of them and silently discards the rest. The request still returns HTTP 200, and the response reports no error and no warning, so a query that ignored half of what you asked for looks like a query that worked. That silent discard applies when the field accepts every operator you supplied. If any supplied operator is not accepted on the field, the request fails with an error instead, so a wildcard paired with equals on a restricted field still returns its HTTP 400.

Of the eight text operators, matches ranks last. On a field that accepts matches, pairing it with any other operator means matches is the clause that gets dropped. The property loan type fields do not accept matches at all, so supplying it there makes the request fail instead. These are the openLien loan-type fields: allLoanTypes, juniorLoanTypes, and firstLoanType through fourthLoanType.

Two different operators on the same field cannot be combined in one request. To match any of several values, use inList. For two genuinely different match rules, send one request per rule and merge or filter the results in your own application.

The wildcard operators (contains, startsWith, endsWith) are supported only on the low-cardinality enumerated fields (for example address.state, address.zip, general.propertyTypeCategory, general.propertyTypeDetail, and most other status and type enums). On the high and medium cardinality text fields they return an HTTP 400 error. See Field-Specific Restrictions for the full list.

Not every operator is available on every field. The wildcard operators (contains, startsWith, endsWith) are not supported on the high and medium cardinality Property Search text fields below, grouped by object. Sending a wildcard operator on one of these fields returns an HTTP 400 error naming the field and operator, with guidance on the operators that are supported there.

On these fields, use the supported operators instead: equals for an exact value, inList and notInList for a known set of values, and matches with a single complete stored value, as on the tag field permit.allTags. owner.firstName and owner.lastName additionally support containsWords for owner-name search (see Searching by owner name).

The wildcard operators remain available on the low-cardinality enumerated fields, for example address.state, address.zip, general.propertyTypeCategory, general.propertyTypeDetail, the numeric geography codes (address.countyFipsCode, address.cbsaCode, address.csaCode), and most other status and type enums. Note that the restriction applies to the text title fields (address.cbsaTitle, address.csaTitle), not to their corresponding numeric code fields.

A second restriction worth knowing about is previousOwner.fullName, which is exact-match-only: it supports equals, inList, notInList, and matches, and it does not accept containsWords, contains, startsWith, or endsWith. matches is no exception: it also requires the complete stored name. See Searching by previous owner.

The Property Search API Reference carries worked request-body recipes for building filters, property types, quicklists, and request options. If you send a wildcard operator on a restricted field, the API returns an HTTP 400 naming the field and operator. The loan-type fields are the exception: supplying matches there fails without that guidance.

To find a property by its owner's name, use the containsWords operator on owner.firstName and owner.lastName. containsWords performs a tokenized, order-insensitive, case-insensitive word match, so a first or last name matches regardless of how the owner's name is stored or the order its parts appear in. When you supply both owner.firstName and owner.lastName, a property matches only if both names appear on the same owner record. When both names use containsWords, satisfying one name through one owner and the other through a second owner is not a match. Supplying a single name part matches it against either owner. A supplied name part is matched against the whole of the owner's stored name rather than against one name component, so owner.firstName and owner.lastName are interchangeable when both are supplied. This is the supported way to search by owner name, and it replaces wildcard matching on owner-name fields. The same-owner rule applies when both names use containsWords or both names use equals or inList. If you use containsWords for one name and equals or inList for the other, the API checks each name separately. The two names can then match two different owners on the same property.

equals, inList, and matches are also accepted on owner.firstName and owner.lastName. They compare a value against the stored name component itself: the stored first name on owner.firstName, or the stored last name on owner.lastName. A value that is not the complete stored component, such as a full name supplied to owner.lastName, returns no results. With a single value, matches behaves like equals. When you do not know the stored format, use containsWords.

A search that uses containsWords on either name requires a location, such as a city and state, a ZIP code, or a full address. Without a location, the request returns HTTP 400. An owner-name search that uses only equals or inList does not require a location. For a containsWords search, the options.ownerNameAddressMatchMode request option selects how the location is handled:

Use exact mode when you need to confirm whether a specific person is on the owner record at a known address (for example, probate and estate research). In exact mode the response adds an ownerNameMatch object under meta.results carrying matchedParcelCount (the total, and the value to use for the zero / one / more-than-one decision), ownerNameMatchCount and trustMatchCount (attributions explaining how those parcels were reached, which overlap rather than dividing the total between them), and matchSource, which indicates which address the match came from. ownerNameMatchCount counts parcels carrying every supplied name part on the current owner record, and trustMatchCount counts parcels reached through the trust deed look-back. For a trust-owned property that look-back also matches recent deed parties, and both names must describe the same deed party. standard mode omits the ownerNameMatch object.

Confirm whether John Smith is on the owner record at a specific address:

This capability is announced in the Owner-Name Property Search release note in our Release Notes collection.

Owner-name search finds properties a party owns today. To find properties a party previously sold, use previousOwner.fullName. This is the criterion to reach for when you are researching a fix-and-flip investor, a builder, or any party whose activity you track by what they have offloaded rather than what they currently hold.

previousOwner.fullName is exact-match-only:

Because there is no tokenized or partial matching here, supply the party's name as it appears on the transaction. If you are unsure of the exact spelling or the entity suffix, pass several variants with inList rather than guessing a single form.

One important limitation: this criterion matches the seller of record on a property's two most recent sales. It does not search a property's full ownership or transaction history, so a flip that happened three or more transactions ago will not match. If you need everything a party has ever transacted, use Investor Profile instead.

This capability is announced in the Previous-Owner Property Search release note in our Release Notes collection.

Looking up properties in a known set of cities:

Looking up properties in a specific subdivision:

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

Searching for properties whose ZIP code begins with a prefix:

Following these patterns will keep your searches fast, your results predictable, and your integrations resilient as your data volume grows.