DEV Community

TechnoXander
TechnoXander

Posted on

Designing a name-matching service people can argue with

Name matching looks like a solved problem until you deploy it in a market where names carry particles, transliterations, honorifics and business trading names. Then it becomes a product decision disguised as an algorithm.

Here is the design I would defend in a review.

Separate the score from the outcome. The matcher returns a score and a reason. The scheme mapping turns that into Match, Close Match or No Match. Keeping these apart means you can retune the thresholds without retraining the model, and you can explain a result without exposing the model.

Make the reason a first-class field. Not a debug log. A field that travels with the response, appears in the portal, and can be shown to a customer. Something like reason: TRANSLITERATION_VARIANT or reason: BUSINESS_TRADING_NAME. This is the single highest-value change you can make, because it turns an unexplainable answer into a reviewable one. The matching considerations are set out in matching algorithms in VoP, and the reason field is what makes them operable.

Version everything. Matcher version, threshold set version, normalisation rules version. Store the version on every response. When match rates shift in six months, you will need to know whether the population changed or the logic did.

Normalise explicitly, not magically. A written order of operations, applied in a fixed sequence:

1. Unicode NFKC
2. Trim, collapse whitespace
3. Case fold
4. Remove punctuation except hyphens and apostrophes
5. Expand known honorifics (Mr, Mrs, Dr, Mx)
6. Handle particles (van, von, de, bin, al) as tokens, not noise
7. Transliterate to a canonical script
8. Preserve the original string alongside the canonical one
Enter fullscreen mode Exit fullscreen mode

Step 8 is the one teams skip, and it is the one that saves you in a complaint. Never destroy the input.

Do not normalise away meaning. "Mohammed" and "Muhammad" may be the same person. "Al Rahman Trading" and "Al-Rahman Trading Co" may be the same entity. "Smith" and "Smyth" may not be. A matcher tuned for recall will merge the last pair and create a false positive that a human then has to unwind. The VoP name matching quiz is a useful calibration exercise for a product team, because it forces the argument about which errors you would rather make.

Treat business names as a different problem. Legal name, trading name, group name and brand name are four different strings. A personal-name algorithm applied to companies produces Close Match noise at scale. If your institution serves corporates, this is where the exceptions queue comes from.

Log the decision, not just the request. Every response should record: input string, canonical string, matcher version, score, threshold band, outcome, and the reason. That record is what you produce when someone asks why a payment was allowed.

Test with the population you have. A test suite of synthetic European names will pass and tell you nothing. Sample real name pairs from your own exceptions queue, with permission and with the data minimised, and use those. The distribution is the product.

Publish the limits. Tell the consumer of the API what the matcher does not do. It does not verify identity. It does not confirm ownership. It does not resolve transliteration across every script. It gives you a signal about a string. Teams that overstate the signal end up in disputes about what the check meant.

Two operational notes.

First, the routing and verification mechanism determines which institution you are asking, and a correct answer from the wrong institution is still wrong. Log the route alongside the result.

Second, the scheme rules are the contract. The EPC VoP rulebook defines the message set and the expected behaviour, including what to do when no response arrives. Build the timeout path before the happy path. It is the part that runs during an incident.

The same argument applies to investigation: retrieval, not judgement, is the bottleneck.

The conclusion is simple. A matcher people can argue with is worth more than a matcher that is 2 percent more accurate, because the arguable one gets used, monitored and improved. The accurate one gets switched off after the first complaint nobody could explain.

Top comments (2)

Collapse
 
fintechrailsdigest profile image
Fintech Rails Digest •

the reason field is the part most VoP implementations miss, and calling it the highest-value change matches what we've watched in production. a score with no reason turns every borderline call into a support ticket, because the reviewer and the customer argue past each other. the fixed normalisation order matters too: teams usually inherit a regex someone wrote in one afternoon, and that order becomes load-bearing infrastructure nobody dares touch later. keeping the original string alongside the canonical one is the step that settles complaints.

Collapse
 
technoxander profile image
TechnoXander •

Absolutely. The original input is just as important as the final score. When a customer challenges a result, teams need to show exactly what was received, how it was normalised and why the decision was reached. Without that, even a good matching engine becomes difficult to defend in production.