When you search Property Search by owner name with the containsWords operator, the search also matches common nicknames. A search for "Bill" finds owners named William, and a search for "William" finds owners named Bill. This article explains which searches match nicknames, how the matching works, and how to get an exact match when you need one.

Which searches match nicknames

Nickname matching applies only to the containsWords operator on owner.firstName and owner.lastName.

equals, inList, notInList, and matches are exact. They never match nicknames.
containsWords is supported only on owner.firstName and owner.lastName. On any other Property Search field, including owner.fullName and previousOwner.fullName, the request returns HTTP 400.
A containsWords search requires a location, such as a city and state, a ZIP code, or a full address. A containsWords request without a location returns HTTP 400.

How nickname matching works

Nickname matching works in both directions. A search for a formal name matches owners stored under a common nickname for that name, and a search for a nickname matches owners stored under the formal name. Nickname matching applies to each name you supply.

Each name in the first column matches each nickname in its row, in both directions:

Name	Nicknames that also match
Robert	Bob, Bobby, Rob
William	Bill, Billy, Will, Liam
Richard	Dick, Rich, Rick, Ricky
Margaret	Maggie, Marge, Meg, Peggy
Katherine	Kate, Kathy, Katie, Kay
Elizabeth	Beth, Betty, Liz, Libby

This table shows examples only. It is not the full list of nicknames.

Keep these points in mind:

Different spellings can have different nicknames. Katherine and Kate match each other, but Catherine and Kate do not.
Some nicknames belong to more than one name. Rick is a nickname for Richard, Eric, and Frederick. A search for "Rick" matches owners with any of those names, but a search for "Richard" does not match owners named Eric. For this reason, a search for a nickname can return more properties than a search for the formal name.
Nickname matching does not correct spelling. A misspelled name does not match the correct spelling.

Whole words only

containsWords matches whole words. It is not a prefix or wildcard search, so a search for "Vanes" does not match "Vanessa". The match is not case-sensitive.

When a value contains more than one word, every word must match, in any order. For example, owner.lastName with containsWords set to "Van Buren" matches owners whose name contains both "Van" and "Buren".

First name, last name, and the same-owner rule

With containsWords, a name you supply can match any part of the owner's stored name, so owner.firstName and owner.lastName are interchangeable. A search with owner.firstName set to "Smith" and owner.lastName set to "John" returns the same properties as a search with owner.firstName set to "John" and owner.lastName set to "Smith". You can also supply both names in one field, for example owner.firstName set to "John Smith".

When you supply both owner.firstName and owner.lastName, a property matches only if both names appear on the same owner record. 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.

Keep these points in mind:

The same-owner rule does not apply when you mix operators. 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.
Some records store several people as one owner. A county record can list two people in one owner entry, for example "John Smith & Mary Jones". Both names are then on the same owner record, so a search for John and Mary can match it.
Nickname matching applies to each name. A search for "Bill" and "Smith" matches an owner stored as William Smith.
The rule also applies in exact mode. With options.ownerNameAddressMatchMode set to exact, when a trust owns the property, the search also checks two deed parties: the sellers on the property's most recent deed, and the buyers on the deed before it. Both names must describe the same deed party.

How to get an exact match

There is no request option that turns off nickname matching for containsWords. To search without nicknames, use an exact operator:

equals matches the complete stored first name on owner.firstName, or the complete stored last name on owner.lastName. An equals search for "Bill" does not return owners stored as William. The match is not case-sensitive.
inList matches any of several complete names. Use it to allow specific name forms, for example "William" and "Bill", without the other nicknames.

This request uses containsWords. It finds owners named Bill Smith and owners named William Smith in Phoenix, Arizona:

{
  "searchCriteria": {
    "query": "Phoenix, AZ",
    "owner": {
      "firstName": { "containsWords": "Bill" },
      "lastName": { "containsWords": "Smith" }
    }
  },
  "options": {
    "take": 25
  }
}

This request matches the stored first name William or Bill exactly, with no other nicknames, and the stored last name Smith:

{
  "searchCriteria": {
    "query": "Phoenix, AZ",
    "owner": {
      "firstName": { "inList": ["William", "Bill"] },
      "lastName": { "equals": "Smith" }
    }
  },
  "options": {
    "take": 25
  }
}

When a result looks unrelated

Nickname matching can sometimes return an owner who does not seem to match your search. This happens when a nickname is also used as a surname, or when two different names can both be short for the same longer name. Because a name you supply can match any part of the owner's stored name, a first-name search can then return owners who have that word in their last name.

To remove unrelated owners from your results:

Supply both the first name and the last name with containsWords. The same-owner rule removes most unrelated matches.
Use equals or inList when you know the exact stored name.
To confirm whether a specific person is on the owner record at a known address, use exact mode with a structured address and a containsWords search. See Searching by owner name.

Text Search Grammar Best Practices: every text operator, and the full owner-name search workflow, including exact mode.
BatchData Property Search Request Body Reference: a quick reference for building Property Search request bodies.

How Owner-Name Matching Works in Property Search