Understand results and scores

Plan: Death Verification API · For: Developers and businesses · Time: 5 min read

Every lookup returns one of three results.

Result	Meaning	What to do
`found`	We matched a deceased person to your query with high identity confidence	Read the source obituary, then act under your own process
`possible_match`	We found a same-named decedent, but not enough matched identity details to be sure it's the same person	A person should review it. Never auto-confirm a death from `possible_match`
`not_found`	No qualifying obituary in the sources we searched	Not proof of life. The response includes `not_proof_of_life` and an `interpretation` note

**confidence** is a match score from our scoring model. It's not a probability. found needs a high score (85 or above) and no conflicting details. Scores from 50 to 84 are possible_match, and lower scores are not_found.
**confidence_band** puts the score in a band for easy display.
**review_recommended** is a flag, not a fourth result. When it's true, have a person check the match before you act.
**scoring_reasons** explains which details matched or conflicted.
**match is the best candidate. candidates** lists others we considered. Both are empty on not_found.
**search_scope** shows which sources were checked: stored obituaries, funeral-home listings, newspapers, and the web.

Identity anchors: middle name, city, and birth year. If the obituary states a different value, that candidate is dropped. If the obituary leaves it out, the result stays possible_match.
Name and state alone are deliberately cautious. Strangers can share a name in the same state. Send middle name, city, and birth year when you have them.
**death_date** helps when you already have a death record.
**require_match** makes the obituary confirm each field you list, for example ["dob_year","middle_name","city"]. Use it for batch and automated decisions.
**dob_policy: "reject_conflicts"** rejects only obituaries that contradict your birth date, and leaves ones that don't mention it for review.

`search_depth`	Use it for
`recent`	The shortest window. Good for checks on people who are probably living
`standard`	A wider search
`extended`	The widest search. Needed before you can set `lookback_years`
(leave it out)	The API chooses a depth for you (Auto in the Test Console)

Your account's lookback limit is set by your agreement.