Common gotchas and tips

• Last name is the only required field, but supplying more identifiers materially improves both the candidate pool and the per-row confidence. A request with just a last name will often return many candidates with low scores; adding a DOB or address narrows it dramatically.
• Each phone and email slot is evaluated independently. Supplying phone and phone3 produces a phone outcome and a phone3 outcome in the response; the slot order in the request has no effect on matching. Slots you did not supply are omitted from the row.
• The address block is all-or-nothing. When no address was supplied, the address rollup and the four component fields are all omitted from the row. When the address was supplied but could not be resolved, you get a 400 (or a not_used block if ignore_errors: true is set).
• include_deceased: true adds deceased records but the response carries no deceased indicator. Most use cases (KYC, identity verification, contact validation) should leave this off; only enable it when you have a specific need to match against deceased records and your downstream workflow handles them appropriately.
• return_multiple_candidates: true does not change the row schema. Single-candidate mode just returns the top row; multi-candidate mode returns up to 5 candidates ordered best-first using the same per-row layout.
• Identical candidate rows are collapsed. Two universe records that produce the exact same per-field outcome map against your request appear in the response as a single row. The row count therefore reflects distinct outcome maps, not the count of underlying universe records. Add identifiers to your request if you want candidates to surface as distinct rows.
• Score ties are broken deterministically so that repeating the same request always produces the same ordering, even when several candidates have an identical score. Treat the order in match_results as authoritative for picking a "best" record.