Constituent Search - A Deeper Dive

Rob Dorey

Sometimes developers need to find a constituent record with only a single piece of information to go on, such as an email address, a phone number, or even a nickname. A great way to solve this problem is to use the Constituent (Search) endpoint in the Constituent API. Much like a Google search, the Constituent (Search) endpoint allows you to enter search criteria to locate the constituent you are looking for. We thought it might help developers to take a closer look at search so that they can maximize their use of this feature.

 
What are you searching for?


The Constituent (Search) endpoint applies the search criteria that you supply in the search_text query parameter to a variety of constituent properties to find matching constituent records. Some of these properties have special rules to determine what constitutes a match. The endpoint searches the following properties:

 

• Name. Includes first, last, maiden, nickname, and alias, as well as combinations of first (or preferred) and last such as “John Doe”.
• Spouse’s name. Only if the spouse is not a constituent.
• Lookup ID. See our previous blog on this subject.
• Address number and street name.
• Phone number. Only if at least seven consecutive digits are provided.
• Active email addresses. Only exact matches are selected. 
• Organization name.

 

The include_inactive query parameter indicates whether to include inactive constituents in the search results. By default, the endpoint excludes inactive constituents. The limit and offset query parameters are also available to help with the size of your result set and to provide paging support.

 
How search works

 

As you can tell from the number of properties that the endpoint searches and the number of options that affect the search results, the SQL query for search is very complex. But in a nutshell, search checks each constituent record for matches in the searchable properties using a Soundex code and then assigns a rank based on how well each record matches the search criteria. The search results list constituents by rank so that the most useful matches appear at the top of the list.


Under the hood, the Constituent (Search) endpoint generally applies search text to a SQL WHERE clause as LIKE '@searchText%'. This returns matches that start with the search text. The endpoint is also smart enough to recognize phone numbers (with or without dashes and parentheses), email addresses, and street addresses, and it searches those properties if the patterns match. The endpoint does not currently support wildcards such as "?" or "*" in the search text. 


When you search for a combination of first (or preferred) and last names, you can either start with the first (or preferred) name (“John Doe”) or start with the last name and a comma (“Doe, John”). If the search text includes more than one space, the endpoint accounts for multipart last names. For example, searches for “V Van Gogh” apply “Van Gogh” as the last name search criteria.


We recently received feedback on the Constituent (Search) endpoint requesting the ability to exclude matches that only “sound like” the search criteria. The SKY API team thought this was a great idea, so we added a query parameter called strict_search to do just that. This parameter provides flexibility for developers without adding complexity. To exclude search results that sound like the search criteria but are spelled differently, just set the strict_search parameter to true. The SQL query removes any constituent records with rank values that indicate the properties sound like but are not spelled like the search criteria. For example, in the URL below, the endpoint returns all matches for “Smith” but ignores matches for “Smyth.”

        https://api.sky.blackbaud.com/constituent/v1/constituents/search?search_text=Smith&strict_search=true

 

Please note that the strict_search parameter is set to false by default and that the endpoint returns “sounds like” matches unless you explicitly set the parameter to true.

 

Hopefully, this post sheds some light on constituent search. As always, please let us know if you have questions or suggestions!