Verify API

Reducing false positives

A practical guide for batch probate, trust, creditor, and skip-trace integrations using POST /api/v1/verify.

A false positive in the Verify API means the API returned found (or you treated possible_match as confirmed death) for a different person who shares the subject's name. The API is intentionally conservative with sparse inputs — name and state alone can surface a same-named decedent for human review. This guide walks through what to send, when to use strict matching, and how to handle responses before you automate.

Key rule: possible_match is not a confirmed death. It means we found a same-named decedent but identity was not fully established. Treating every possible_match as your subject is the most common source of false positives in customer integrations.

Precision ladder

Apply these in order. Most trial integrations stop at level 1 and still see same-name strangers — level 3 is what batch probate and trust workflows need.

Level 1

Send richer identifiers

Never query with name + state alone when you have more data. Add middle_name, address.city, dob.year, address.county, or death_date from your source record.

Each field narrows same-name strangers. City and county anchor location; birth year filters candidates born five or more years off; death_date helps when you already have a death record.

Level 2

Understand default identity anchors

Middle name, city, and birth year are identity anchors — conflicts drop candidates; omitted middle name or birth year on the obituary blocks found.

Default matching already drops wrong middle names, wrong cities, and birth years five+ years off. Omitted middle name or birth year on the obituary keeps the result at possible_match — a same-named stranger can still appear if the obituary simply omits that detail.

Level 3

Enable require_match for automation

For batch jobs and automated decisions, list every field the obituary must confirm: dob_year, middle_name, city, county, state, dob_month.

Candidates that do not explicitly state those fields on the obituary are dropped entirely — trading recall for precision. This is the main lever when a false positive is costlier than a missed obituary.

Level 4

Gate your application logic

Only auto-act on found when review_recommended is false and scoring_reasons show corroborated identity — never on possible_match alone.

Inspect match.evidence, match.source_trust (stored index vs web), and scoring_reasons before closing a case or sending notices. Log client_ref for audit trails.

Common patterns and fixes

Risk	Pattern	Fix
High	first_name + last_name + state only	Add middle_name, address.city, and dob.year when available. Use require_match in batch.
High	Common first name (Robert, Mary, James, …)	Send full dob (month + year), city, and require_match on dob_year + city. Consider death_date when you have it.
Medium	dob.year sent without require_match	dob improves scoring but does not require the obituary to state your year. Add require_match: ["dob_year"] for strict confirmation.
Medium	Auto-acting on possible_match	Route to human review or require found with review_recommended: false.
Medium	Web-only match (source_trust: web)	Prefer stored-index corroboration; add require_match; review snippet and obituary_url manually for high-stakes cases.
Low	Nickname / spelling variation (Terry vs Terri)	Send middle_name and city from your source; use require_match on fields you trust. Review scoring_reasons for nickname handling.

Batch recipe: `require_match`

require_match tells the API to drop any candidate whose obituary does not explicitly confirm the fields you list. Default matching already filters extreme conflicts (wrong middle name, wrong city, birth year 5+ years off), but same-named strangers can still appear as possible_match when an obituary omits a detail you supplied. Strict matching is the precision lever for batch probate, trust, and creditor workflows where a false positive is costlier than a missed obituary.

found means high identity confidence for that obituary candidate — but for batch probate, trust, and creditor workflows you should still pair rich request fields with require_match so the obituary explicitly confirms each identifier from your source system.

Allowed values: dob_year, dob_month, middle_name, city, county, state. In CSV batch jobs, enable Strict matching on every row or add a require_match column (e.g. dob_year middle_name city). Only fields present on that row are enforced.

Rich identifiers (manual review friendly)

{
  "first_name": "Margaret",
  "last_name": "Henderson",
  "middle_name": "Ann",
  "dob": { "year": 1942 },
  "address": { "city": "Austin", "state": "TX" },
  "client_ref": "case-88421"
}

Automated batch (strict — fewer false positives)

{
  "first_name": "Judith",
  "last_name": "Thomas",
  "middle_name": "Ann",
  "dob": { "month": 3, "year": 1947 },
  "address": { "city": "Tampa", "state": "FL" },
  "search_depth": "extended",
  "require_match": ["dob_year", "dob_month", "middle_name", "city"]
}

Strict matching on every identifier you send from your source system. Rows where the obituary omits any listed field return not_found instead of a same-named stranger.

Birth date: scoring vs strict confirmation

Sending dob in the request body is not the same as strict date matching. By default, dob is a scoring input: it helps rank candidates, can trigger page scraping to find a birth year, filters extreme year conflicts (five or more years off), and can promote a match to found when the obituary agrees — but if the obituary omits the birth date, the API may still return possible_match for a same-named decedent. To require the obituary text to confirm your birth year or month, add require_match.

Full detail in reducing false positives guide.

Response fields to check before acting

We found a same-named decedent, but not enough matched identity signals to be sure it's the same person. A human should review before acting — never auto-confirm a death from possible_match.

Field	How to use it
result	Only treat found as actionable in automation when other signals agree. Never auto-confirm from possible_match.
review_recommended	When true, route to human review even if result is found — common with web-only or partial corroboration.
scoring_reasons	Step-by-step factors: middle_name_not_corroborated, stored_common_name_requires_disambiguator, require_match_filtered, etc.
match.evidence	name_match, location_match, dob_match — shows what the obituary actually corroborated (e.g. year_only vs exact_date).
match.source_trust	stored (indexed obituary) vs web (supplemental historical). Stored matches are generally more reliable.
confidence / confidence_band	Supplementary signal — do not replace identity field review or require_match policy.

Do not

Treat possible_match as proof of death in automated workflows.
Query with name + state only when your source file has city, middle name, or birth year.
Assume sending dob in the body requires the obituary to show that date — use require_match for that.
Ignore review_recommended on found results from web-only sources.
Use extended depth and include_survivors on every row unless you need heirs or older deaths — they add latency, not precision.

Verify API reference — request fields, identity anchors, strict matching
API FAQ — require_match, possible_match, dob vs strict
Developer scoring guide — thresholds and scoring_reasons