Constituent Search - A Deeper Dive
Published
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
The
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
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
https://api.sky.blackbaud.com/constituent/v1/constituents/search?search_text=Smith&strict_search=true
Please note that the
Hopefully, this post sheds some light on constituent search. As always, please let us know if you have questions or suggestions!
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!
News
SKY Developer Announcements
03/07/2018 8:35am EST
Leave a Comment