Enhanced Best Match

Enhanced Best Match Logic

Please note that the GET /patients/bestmatch endpoint has been deprecated in favor of the new Enhanced Best Match endpoint.

The enhanced best match API call requires the following fields for input:

  • First Name
  • Last Name
  • Date of Birth

The following fields are optional and help confirm searching for the correct patient:

  • Sex
  • SSN (strongest input)
  • Address
  • Home Phone
  • Mobile Phone
  • Zip 
  • City 
  • State

Note: We recommend asking the patient if they have a scheduled appointment for today at this location. In the case where the patient does NOT have a scheduled appointment, you might consider asking for TWO of these fields to ensure a better match and avoid creating a duplicate patient. In the case of phone numbers, you could display home and mobile separately since there is a higher likelihood of a better match score if two are provided. 

Soundex Search

One of the strongest tools in the enhanced best match search is utilizing usesoundexsearch flag. By setting this value to “True”, names that are spelled differently but pronounced the same, such as Aaron and Erin, will be returned in the search. 

If patients input their name incorrectly to either athenaNet or a validated solution outside of athenaNet, we will still return their information in the search. Using the Soundex search can lower the strength of match on the patient.

Strength of Match

Another benefit of our enhanced match is a “strength of match” ranking that is applied to each result.  An exact matching of multiple fields including DOB and First Name / Last Name, will return result scores equal or higher than 23, which is considered as a great score for patient matching.  The more fields included in the API that match the patient, the higher the resulting score.  

For patient matching, athenaNet considers a score of 26 or higher an automatch. Please note that an API responses for an automatch will only contain one patient unless the returnbestmatches parameter is set to TRUE. The lowest score returned via this search is a score of 16, which will denote a partial but unconfirmed match. 

When using Soundex for matching, the score returned for a patient will be lower than if the name was properly input, however, the score will be high enough to be returned through the call. Results lower than 16 are not returned in this call.  Use the MinScore input to return results greater than or equal to the input value to have more accurate matches returned.


Scoring occurs in this API using an existing athenanet algorithm where matching more fields boosts the match score.  Preliminary matching is based on Soundex attempting to match the required fields, and whether or not the SSN matches a patient. Exact matches of first name, last name and date of birth will return a score of 23.  If the SSN and name also matches, then it is considered an “exact match” and will return a score of 38 or higher.

Patient matching through SSN allows the SSN number to be off by two digits resulting in an auto match for a patient.  For example, 123456789 would match with 123456788. This logic is in place due to typographical mistakes that can occur during data import.  We do not recommend using SSN as the only field to match a patient. DOB allows for partial matches on the day, month, and year which can vary results returned in the call.

Note: If a match is not found, we recommend displaying a message on any patient-facing UI that they appear to be a new patient and if they believe they are an existing patient in our system, to please visit the front desk. Conversely, if a match is found, we recommend displaying a message somewhere in the UI to please visit the front desk if it is NOT them. This API will return more results than the “best match logic” API so we need to be more mindful of patient matching.  Currently, only the best scoring patient is outputted through this endpoint. 

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others