Constituent Duplicate Search Array Filters Not Working

Levi Magnus

Hi,

The constituent duplicate search endpoint provides filters for both email and phone that must be provided as an array of strings. According to the docs, providing these as request parameters should filter for records that match the specified email addresses / phone numbers associated with the constituent, but they seem to have no affect on the search result rankings. All other filters work as expected, it's only the ones provided as arrays that seem to be broken.

For context, we're using this endpoint for our constituent matching system, to attempt to match user's who donate on our platform with existing constituents in RE.

As an example of what I mean, in the SKY Developer Cohort test environment I have a constituent named Levi Magnus with a single email address levi@trellis.org. When I hit this endpoint with the last_org_name parameter set to “Magnus” and the email parameter set to ["levimagnus15@gmail.com"] I get back a single result which is my constituent. What's unexpected is that the rank returned in the DuplicateSearchResultRead response for the constituent is ‘1’, implying a perfect match. I would expect the rank to be less than one due to the provided email not matching the constituent. If I hit the endpoint again with the same last name parameter set, but instead of email provide the first_name parameter as “Bob” I get no results back indicating no match. If I provide first_name as “Lev” which is close to Levi I get back a single result with rank ‘0.9166666’, indicating a close, but not perfect match.

Based on my testing it appears the email filter is not working as intended, or at least not how I'd expect it to. Any insight into how this array filter is working would be great. If this is not the correct place to post potential bugs with the API please let me know!

Thank you,

Levi

Alex Wong

@Levi Magnus
have you try providing the email as a string instead of array?

Levi Magnus

@Alex Wong
Yes, if you ignore the typing and pass it as a string instead of an array there's no error, but it still doesn't filter the results. It still returns matches with rank ‘1’ even when the email doesn't match the constituent.

Alex Wong

@Levi Magnus
How the ranking number works is going to be depends on Blackbaud's algorithm, so it's hard to say it is or isn't correct. 1 may not neccessarily means a perfect match. (i actually tested some, I sometime even get 1.01 as rank).

another issue is the parameter type of array. you are understanding it as json array of string. this isn't true and Blackbaud can definitely better document this with examples. So you are not going to specify ["email@email.com","email2@email.com"].

Instead, if you look at the constituent list API endpoint. one of the parameter is constituent_id which is also an array of string. and the documentation is better here where it gave you example.
https://developer.sky.blackbaud.com/api#api=56b76470069a0509c8f1c5b3&operation=ListConstituents

Meaning for the duplicate search, if you are to specify email, you are specifying:

email=email@email.com

if you want to specify more than 1 email for searching, you will do:

email=email@email.com&email=email2@email.com

Levi Magnus

@Alex Wong
For reference, we're using Typescript with the types generated from the Open API spec of the NXT API, which has email in the query parameters for GetDuplicateSearchResults under ConstituentOperations defined as an array of strings:

/** A filter for records that match the specified email addresses. */

email?: string[];

Which gets passed in the encoded request url in the form:

?email[]=firstemail@email.com&email[]=secondemail@email.com

But as I mentioned, even if we ignore the defined type and just provide ?email=email@email.com it is still not filtering the returned results by email matches as expected unfortunately. Thank you for taking the time to look into it and do some testing of your own though!

I've reached out to one of the Sr. Software Engineers at Blackbaud directly via the Social Good Startup Slack channel, so I'm hoping they'll be able to provide some insight into what's happening behind the scenes here with the ranking.

Alex Wong

@Levi Magnus
I call API based on documentation and has been working well. So maybe the issue is with the Open API spec that isn't defined properly.. you can work this out with blackbaud.

Of the test I have done, searching based on name, part of name, and use of email address. I am able to get top ranked result back correctly. As mentioned, 1 is not necessary means perfect match from what I have seen with my test. So if you do have addtional info from the engineer at blackbaud do share here on this post. Thx