Matching, confidence & partial names

Match modes

The match field sets the fuzzy-match tolerance, applied uniformly across every jurisdiction, so behaviour is consistent no matter which states you hit. Whatever mode you choose, supplying a dob or age is the strongest lever on accuracy — it verifies identity and pushes matchConfidence toward 1.0.

Read matchDetail to see exactly why a record matched — it splits the match into strategies (for example {"lastName":"exact"} vs {"firstName":"nickname"}), the fieldsPresent on the record, and any signals. The flat matchBasis array carries the same information mixed together (for example ["lastName", "firstName", "dob", "lastName:exact", "name_match"]) so you can set your own confidence threshold for auto-accept versus manual review.

Nickname-aware name search

Under balanced (and broad), a firstName is expanded to its common nicknames and variants before matching — so a search for John also surfaces Johnny and Jack, and a search for Jonathan matches records filed as John. The expansion used is echoed back on every record in the output-only nicknames[] array (parity with a legacy firstName_nicknames field). It is computed at serialize time and is never presented as data published by a jurisdiction.

The match-strategy vocabulary — the complete list

Every record tells you how it matched, per field, in matchDetail.strategies (and, in the older flat form, as the field:strategy tokens of matchBasis). This is the whole vocabulary — the list is closed. Any token the engine emits that this mapping does not define arrives under matchDetail.other rather than appearing here, so a new token can never quietly pass for one of these.

Rank is the ordering contract, not a score: 1 is the strongest evidence, and results sort by surname rank then given-name rank, with legal-name hits ahead of alias-only hits. Ceiling is the cap the strategy puts on matchConfidence, applied automatically so a widened hit is never reported as certainty. The cap is lifted in exactly one case: you supplied a dob and the record’s full date of birth matched it.

The alias key appears only when an alias, rather than the registered name, produced the hit — and it carries only exact, prefix and fuzzy. Aliases are published unstructured and in mixed word order, so every token is tested and the response does not assert which one was the given name; that is also why the given-name-only strategies are not offered on it. An alias-only hit caps at 0.55, the lowest value the engine produces.

Partial name search

When you only know part of a name, set prefixMatch and the name you send is treated as the start of a name. Searching thom returns Thomas, Thompson and Thomason — on the first name, the last name, or both — and it is matched against every recorded alias as well as the registered name.

{
  "query": {
    "firstName": "thom",
    "lastName": "and",
    "prefixMatch": "both"
  }
}

// → Thomas Anderson, Thompson Andrews, ...

prefixMatch accepts "firstName", "lastName", "both", or a list. When both fields are prefix-matched, a record must satisfy both.

The rules

Per-field control with nameMatch

prefixMatch is the shorthand. When you want to drive matching yourself, send nameMatch and list exactly the strategies you want for each field. Anything you leave out is off for that field, and nameMatch overrides both prefixMatch and match.

{
  "query": {
    "firstName": "Robert",
    "lastName": "thom",
    "nameMatch": {
      "firstName": [],
      "lastName": ["prefix"],
      "aliases": true
    }
  }
}

// firstName: []          exact only, no nickname widening
// lastName:  ["prefix"]  prefix | fuzzy
// aliases:   true        also match aliases (the default)
// → Robert Thompson  (not Bob Thompson)

Which name matched — legal or alias

A prefix is matched against every recorded alias as well as the registered name, so a variation of a first name still finds the person. Every record tells you which name did it, so an alias hit never reads as “you returned the wrong person”:

{
  "name":        { "first": "Ryan", "last": "Lloyd" },
  "aliases":     ["BRANDON THOMPSON"],
  "matchedName": { "value": "BRANDON THOMPSON", "type": "alias" },
  "matchBasis":  ["lastName:prefix", "alias:prefix", "alias_match"],
  "matchConfidence": 0.55
}

matchedName.type is "legal" when the registered name matched and "alias" when an alias did. Send "nameMatch": { "aliases": false } to search registered names only.

How results are ordered

The ordering is deterministic, so a customer paging through results never sees them shuffle. An exact surname match always outranks a prefix match. In order:

1. Surname match strength — exact, then nickname, then prefix, then fuzzy
2. First-name match strength, on the same scale
3. Legal-name matches before alias-only matches
4. matchConfidence, highest first
5. Last name, first name, then date of birth
6. Record id — the final tie-break, so the ordering is total and repeatable

A partial match is a candidate, not a confirmation

Widening a search widens the risk of returning the wrong person, so a partial-name hit is never presented as certainty. matchConfidence is capped by how the name matched:

The one exception: if you supplied a dob and the record’s full date of birth matches it, the cap is lifted — a confirmed date of birth is identity evidence that a partial name match is not. Supplying a dob or age alongside a prefix search is the single best way to keep precision while widening recall. See Searching by date of birth.

Every result is a candidate match, not identity verification. That is true of any search here and it is doubly true of a partial-name search: read matchBasis, matchedName and matchConfidence, and confirm identity against the linked official record before acting on a result.