Matching, confidence & partial names

The surname is the anchor

These rules hold in every mode — on the cache and on a live source — because matching is applied on top of every source’s output.

• lastName is required. A query with no surname is refused with 422 guard_unbounded_query. Both lastName and the shorthand last are accepted.
• The surname must corroborate. A record whose surname neither equals nor prefix-matches your lastName is dropped. This is the only hard name filter.
• A record missing a first name is KEPT and flagged firstName:absent with a small confidence penalty — we cannot disprove your firstName, so it is never silently dropped.
• Case-insensitive. smith, Smith, SMITH are identical.

The two surname strategies — nameStrategy

First-name matching and nicknames

When you supply firstName, it is scored after the surname corroborates. Both sides are folded through a small, conservative nickname table first — Bob/Bobby/Rob → Robert, Bill/Will → William, Jim → James — in both directions. A nickname hit reads as firstName:exact (the two folded names became equal). A first-name mismatch does not drop the record — it only lowers its confidence, because the surname is the only hard filter.

Prefix (partial-name) matching — prefixMatch

prefixMatch requests prefix matching on a named field explicitly, and is where the 3-character floor lives. It accepts "firstName", "lastName", "both", or a list.

{ "query": { "lastName": "hamil", "firstName": "al", "prefixMatch": "lastName" } }

The floor guards the bulk-download shape, not short surnames. A 2-character exact surname is always fine.

The match vocabulary on the wire

Every record tells you how it matched, in matchBasis (space-separated field:how tokens) and matchDetail (one plain sentence). The surname/given tokens are exact, prefix, absent, mismatch, notQueried; the dob tokens are match, year, monthYear, age, ageFromDob, absent.

{
  "name": { "first": "ROBERT", "middle": "E", "last": "SMITH", "suffix": "" },
  "matchConfidence": 0.95,
  "matchBasis": "lastName:exact firstName:exact dob:match",
  "matchDetail": "name and full date of birth agree",
  "matchState": "dob_match",
  "unverified": false
}

How matchConfidence is built

matchConfidence is not a probability — it is a sum of fixed evidence contributions, clamped to [0.0, 0.99], so a name-only match can never present as certainty.