API docs / Verify

Death Verification API

Single endpoint for one-shot obituary lookups. Returns

found

possible_match

, or

not_found

with confidence and evidence.

Reducing false positives guide — identity anchors, require_match, and batch recipes for probate and trust workflows.

Free sandbox keys

Build and test the response before you talk to sales about production volume.

Keys that start with om_test_ return deterministic fixtures. They do not use quota, and they are not rate limited. Sandbox responses include "sandbox": true. The outcome follows the last-name initial: a–h found, i–p possible_match, q–z not_found. That behavior is documented on the API overview.

Request test keys and we will provision a sandbox. The Death Verification API is quoted by sales. This page does not publish per-lookup or volume prices.

Request test keys

What every result includes

The fields below are on the documented Verify response. Open the obituary and judge the match yourself.

Fields included on a Death Verification API result
Field	What it tells you
result	found, possible_match, or not_found.
confidence and confidence_band	A score plus a label: high, moderate, low, or none.
match.matched_name	The name on the notice, when there is a match.
match.death_date	The date of death when the source gives one.
match.location	City and state when the notice includes them.
match.obituary_url	A link to the obituary so you can read the source.
match.source	The publisher or funeral home.
match.survivors	Relatives named in the obituary, when that text is available. Not a legal heir determination, and not a phone number.
not_proof_of_life	On not_found, an explicit statement that a missing notice is not evidence the person is alive.

Batch integrations: start here

If you are evaluating the API on a CSV or automating death confirmation, read reducing false positives before tuning requests. Name + state alone will surface same-named decedents as possible_match — use richer fields and require_match for precision.

Coverage / limitations

Results are based on searched obituary sources and web results. not_found is not proof of life or a death-registry result.

Endpoint

POST /api/v1/verify

Production base URL: https://api.obituarymonitor.com/api/v1/verify

Developer portal

API-primary customers sign in at /login and land on the developer portal:

Overview — quotas, monthly usage, quick links
Guide — integration walkthrough (getting started, search depth, results)
Test console — run live verify requests against your API key
Batch Verification — upload a CSV for batch verify
Watches — scheduled re-checks and webhook delivery
Usage — volume charts, result breakdown, recent request log
API Keys — create and revoke keys (shown once at creation)
Compliance — acceptable-use terms for the Death Verification API
Support — write to us about your integration, quota, or a result that looks wrong

Account limits (lookback years, monthly and daily quotas, and extended concurrency) are configured for your account. Contact support to change them.

Authentication

Send your API key in the Authorization header:

Authorization: Bearer om_live_xxxxxxxx

Keys are created in the developer portal under API Keys. Your account must have api_access enabled.

Request schema

Required: first_name and last_name, plus at least one disambiguator (otherwise 400 invalid_request):

address.state (2-letter US state), or
address.city and address.state together, or
address.county and address.state together (county name without "County" suffix is fine — e.g. Travis + TX), or
dob.year, or
dob.month and dob.year together

death_date is optional but strongly recommended when you already have a death record — it improves scoring and can confirm common names. It does not replace a disambiguator by itself.

Field	Type	Notes
first_name	string	Required
last_name	string	Required
middle_name	string	Identity anchor when provided. Conflicting middle names on the obituary drop the candidate; an omitted middle name blocks `found`. Compatible initials (e.g. "M." ↔ Marie) count as a match.
dob.month	1–12	Optional; send with dob.year. Strengthens identity scoring and can promote to found when month and year both match the obituary. Does not by itself require the obituary to show your birth month unless you list dob_month in require_match.
dob.day	1–31	Optional birth day (1–31); requires dob.month and dob.year. When the obituary prints a full birth date that matches, evidence.dob_match is exact_date and identity confidence rises. Day alone is not a require_match field.
dob.year	1800–2100	Identity anchor when provided. Improves scoring and ranking; may trigger obituary page reads when birth year is not in the search result. Birth year five or more years off drops the candidate. If the obituary omits birth year, the result stays at possible_match — not found. Sending dob alone does not require the obituary to state your year; add dob_year to require_match for that.
address.city	string	Identity anchor when provided with `address.state`. Conflicting cities drop the candidate; metro-area pairs (e.g. Chicago/Evanston) still match.
address.state	string	Strongly recommended; satisfies disambiguator when present (2-letter US state)
address.county	string	Optional disambiguator with `address.state`. Use when your source data has county but not city (typical for death-record / heir lookups). County is resolved against our funeral-home directory — including search results on known funeral-home domains.
death_date	string or object	Known date of death: ISO `YYYY-MM-DD`, `YYYY-MM`, `YYYY`, or `{ year, month?, day? }`. Strong match signal when obituary death date aligns.
address.line1	string	Optional street line; trailing `City, ST` may be parsed when city and state are omitted
search_depth	enum	Optional. `recent` \| `standard` \| `extended`. If omitted, the API automatically chooses an appropriate depth based on stored obituary inventory, DOB compatibility, and account lookback limits. Customers can still force `recent`, `standard`, or `extended`.
client_ref	string	Your correlation id (echoed in response)
lookback_years	integer (1–20)	Extended depth only. Calendar years back from today for web fan-out and stored inventory death-date window (each year ≈ 365 days on indexed obituaries and funeral-home listings). Defaults to your account `max_lookback_years` when omitted. Cannot exceed that maximum. Web results are not date-filtered; see `lookback_check` in the response.
require_match	string[]	Strict matching. Each listed field must be corroborated by the obituary or the candidate is dropped. Values: `dob_year`, `dob_month`, `middle_name`, `city`, `county`, `state`. Every entry must match a value you sent elsewhere in the request. Strict: the obituary must explicitly confirm this field or the candidate is dropped.
dob_policy	enum	Optional. `strict` (default) \| `reject_conflicts`. Controls how `require_match` with `dob_year` or `dob_month` treats obituaries that cannot confirm the birth date. `strict` drops them. `reject_conflicts` drops only obituaries whose birth year or age at death contradicts yours; the rest are kept, capped at `possible_match`, and explained in `dob_check`.
include_survivors	boolean	BETA. Family Insights. When `true` and Family Insights is on your account, parse named family from the obituary when a match is found. Uses stored text when available; otherwise fetches the obit page, which can add about 10 seconds. How names are delivered depends on your account — see Family Insights below. Treat as a research aid — accuracy varies.

Birth date: scoring input vs strict confirmation

Sending dob in the JSON body is not the same as require_match.

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 a read of the obituary page 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.

You send	Default (no require_match)	With require_match
dob.year	Score + optional obituary page read; year match can promote to `found`; omit on obituary → still `possible_match`	`dob_year` → drop if obituary does not state the same birth year
dob.month + dob.year	Stronger scoring; both must match obituary to reach `found` via date evidence	`dob_month` → drop if obituary does not confirm month/year
dob.day + dob.month + dob.year	Full date match → `evidence.dob_match: exact_date`; strongest DOB promotion. Response also returns obituary `match.birth_date` when known.	No day-level `require_match` flag yet — use month/year strict fields

When only dob.year is sent and the search result lacks a birth year, the API may fetch the full obituary page to resolve it. Combined with extended depth or include_survivors, responses can take from tens of seconds to several minutes. Set your HTTP client timeout accordingly (we recommend 180s+ for extended + dob).

Example — scoring only (no strict date confirmation)

{
  "first_name": "Terry",
  "last_name": "Wilkes",
  "dob": { "year": 1947 },
  "address": { "state": "OH" },
  "search_depth": "extended"
}

Default matching: birth year used for scoring and page reads; a same-named stranger can still appear as possible_match if the obituary omits the year.

For batch eval or automated decisions, pair your dob with require_match — see the strict matching section below. Many obituaries never state a birth date or age; if strict birth-date matching drops too many of those, add dob_policy: "reject_conflicts" to reject only contradicting obituaries and review the rest.

Identity anchors

How middle_name, address.city, and dob.year affect every verify request.

When you send middle_name, address.city, or dob.year, the API treats them as identity anchors. A candidate whose obituary states a different middle name or city is dropped. A birth year five or more years off is dropped. If the obituary omits your middle name or birth year, the result stays at possible_match — never found. Sending dob alone does not require the obituary to state that date; use require_match for strict confirmation.

Conflict — obituary states a different middle name, city, or birth year (five+ years off) → candidate dropped (may yield not_found even when name + state match).
Missing on obituary — you sent a middle name or birth year but the obituary omits it → result stays at possible_match, not found.
Strict mode — require_match: ["dob_year", "middle_name", "city"] for batch jobs where false positives are costly.

Strict matching: require_match

The precision lever for batch and automated workflows — strongly recommended when you send birth year, middle name, and city from your source system.

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.

Use require_match on batch jobs and automated decisions — especially when you send middle name, city, and birth year from your source system and need the obituary to confirm each one before you act.

List only fields you also send in the same request. Allowed: dob_year, dob_month, middle_name, city, county, state. Strict: the obituary must explicitly confirm this field or the candidate is dropped.

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

Turn on Strict matching when a wrong match would be costly. The obituary has to confirm each field you mark, or that candidate is dropped. In a CSV, use the checkbox for every row, or add a require_match column (for example dob_year, middle_name, city). Only fields filled in on that row are enforced.

When strict filtering removes all candidates, the response is not_found and scoring_reasons may include require_match_filtered:….

Birth date policy: dob_policy

By default (strict), a required dob_year or dob_month drops every obituary that does not state a matching birth date. With dob_policy: "reject_conflicts", only obituaries whose stated birth year (or age at death) contradicts yours are dropped. Obituaries that list no birth date or age, or miss by one year, are returned at most as possible_match with review_recommended: true.

When a match is returned under reject_conflicts, the response includes a top-level dob_check block:

policy — reject_conflicts
status — confirmed | unverified
reason — birth_date_confirmed | age_at_death_consistent | obituary_lists_no_birth_date_or_age | birth_year_near_miss | birth_month_not_stated | birth_month_differs
conflict — always false (conflicting obituaries are dropped)

search_depth

Each verify request counts as one lookup against your monthly quota, regardless of depth.

auto (omit search_depth)

If search_depth is omitted, the API automatically chooses an appropriate depth based on stored obituary inventory, DOB compatibility, and account lookback limits. Customers can still force recent, standard, or extended.

Auto stays on standard. A birth year with no confirming stored row uses dob_unconfirmed_staged_web: other database tables are searched, then one broad web query. Per-year web queries run only when that query returns a plausible obituary, or when you set search_depth to extended. Auto still chooses extended when a supplied death date is older than the standard window, or when include_survivors is set. search_scope.search_depth shows what was applied; search_depth_auto_reason explains why.

Accounts set to database only always search stored obituaries and listings, including older records. Paid web search does not run, and neither an explicit search_depth of extended nor an automatic upgrade changes that. search_scope.search_depth is standard, historical_web_search_checked is false, and search_depth_auto_reason is account_database_only. Extended quota is not used. The result is still found, possible match, or not found.

recent

Stored obituaries and funeral-home listing inventory only. Fastest option; use when indexed coverage is sufficient.

standard

Stored inventory first. A funeral-home name match skips historical web search only when the request has no birth year, or a listing birth year agrees with the one you sent. Otherwise obituaries and newspapers are searched across the longer stored window, then one broad web query. A dated match is ranked above a dateless name-and-state listing.

extended

Deepest coverage: always searches stored obituaries and funeral-home listing inventory first, then adds multi-year historical web search. Set lookback_years to control how many calendar years back from today are searched on the web (up to your account's max_lookback_years). The same value expands the death-date lookback on stored obituaries and funeral-home listing inventory (lookback_years × 365 days). Subject to extended concurrency limits; may return 503 when capacity is saturated.

dob.year helps disambiguate matches but does not change which years are searched — use lookback_years to reach older deaths.

lookback_years chooses which years go into web search queries. A web result whose death date is before the window is dropped unless the obituary confirms your birth month and year; undated web results are kept. Extended responses with a match include lookback_check (omitted when you send death_date):

window_start — first day of the lookback window
death_date — the matched obituary's death date (nullable)
status — inside | outside | unknown (no death date on the obituary)
capped_to_possible_match — true when an outside death was downgraded

A death outside the window adds death_outside_lookback to scoring_reasons. It stays found only when your birth date is confirmed by the obituary (full date, or month and year); otherwise it is returned as possible_match with lookback_capped_to_possible_match.

Result meanings

found

We matched a deceased person to your query with high identity confidence. Safe to treat as confirmed. Stored-index matches rank above web-only signals. Review match.evidence and scoring_reasons before automated action.

possible_match

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. review_recommended is typically true. Treat as a lead, not confirmation.

not_found

No qualifying obituary was found in the sources we searched. This is not proof the person is alive — only that we did not find a death record. Response includes not_proof_of_life: true and an interpretation string.

Getting found instead of possible_match

Tip: name + state alone is deliberately cautious — a stranger can share a name in the same state. Send middle_name, address.city, and dob.year when you have them. For batch or automated workflows, add require_match so the obituary must confirm each field you send — see the scoring guide.

When a result is downgraded, scoring_reasons may include stored_found_requires_disambiguator, middle_name_not_corroborated, or a Middle name conflict / City conflict reason when a wrong-person candidate was dropped.

negative_result_strength

Returned on not_found only.

weak — minimal identifiers; search coverage was narrow.
moderate — reasonable identifiers; standard scope searched.
strong — strong disambiguators (e.g. city+state, county+state, DOB, or death date) and broader search; higher confidence no obituary appeared in scope.

search_scope (response)

Every response includes search_scope describing what was searched. Use it to audit auto-depth decisions and coverage scope. Top-level external_queries_count reflects supplemental search activity (0 for recent depth).

scoring_reasons (top-level and on match) are plain-language strings explaining the outcome — not fixed enum tokens.

Field	Meaning
stored_obituaries_checked	Whether parsed obituaries index was queried
listing_inventory_checked	Whether funeral-home crawler listing inventory was queried
historical_web_search_checked	Whether supplemental historical search ran (false for `recent` depth)
search_depth	Effective depth applied for this request
search_depth_requested	Client value; `null` when auto-detected
search_depth_auto_reason	Why auto chose this depth (e.g. `dob_unconfirmed_staged_web`, `stored_coverage_sufficient`, or `account_database_only`)
years_searched	Calendar years used in web fan-out
lookback_years_requested	Client `lookback_years` value (extended only)
lookback_years_applied	Extended depth year count applied (stored + web window)
stored_name_match_count	Same-name hits in stored inventory for this request
stored_newest_death_year	Newest death year among stored same-name inventory (when probed)
stored_oldest_death_year	Oldest death year among stored same-name inventory (when probed)
has_dob_compatible_stored_match	Whether any stored hit matched submitted birth year
web_search_status	`skipped`, `completed`, or `pending_phase2`
web_search_skip_reason	When supplemental search did not run: `depth_recent`, `listing_inventory_hit`, `stored_inventory_match`, `missing_state`, or `external_search_unavailable`
web_results_raw	Supplemental source results before URL filtering (diagnostics)
web_results_after_url_filter	Results after dropping non-obituary URLs
web_candidates_parsed	Supplemental rows that passed name/obit parsing

County lookup (address.county)

When your source data includes county but not city — common for death-record and heir-identification workflows — send address.county with address.state. City is optional.

County matching uses our funeral-home directory as the authoritative geo source:

Stored obituaries and listing inventory carry funeral-home county directly
City names from obituary text map to county via funeral homes operating in that city
Search results on known funeral-home domains resolve county from the directory (even when the obit is not in our index)

Pure aggregators (Legacy.com, Echovita, etc.) rely on city/state parsed from the search result title or snippet. Pair county-only requests with death_date when names are common.

Biographical profile

A matched response carries match.biographical_profile: captured work, military service, education and places from the obituary. It never changes result or confidence. Included in your plan at no additional cost, within its coverage.

profile_status is ready, pending, unavailable or skipped (no biographical details in the text). When pending, request the notice again later; there is no webhook.
An occupation's evidence cites that occupation. A supported occupation quote does not verify education, places, business_owner, or family counts. Military service has its own evidence. A veteran, branch, or era stored without a checked quote — including every current row, which is only veteran, branches, and eras — is uncertain (citation_not_graded or no_quote). That is captured, not verified. supported requires a checked quote that attributes the service to the deceased. A non-empty quote is not enough when it describes a relative, a memorial line, or no service at all. The portal shows ungraded service as "Captured, not verified" and does not present it as confirmed. CSV veteran, branch, and era columns stay blank unless the value is supported. Education and places are captured fields and have no evidence status.
Where evidence is present, status is supported (a quoted sentence states that field), uncertain, explicit_negative, or not_mentioned.
family appears only when family_access is included, which follows your existing family-access rules. Otherwise quotes that name relatives are withheld.
If the profile lookup fails, the notice is still delivered with {"profile_status": null, "profile_error": "profile_lookup_failed"}.

"biographical_profile": {
  "profile_status": "ready",
  "profile_version": 4,
  "last_refresh_error": null,
  "family_access": "omitted",
  "occupations": [{
    "title": "teacher",
    "employer": "Austin ISD",
    "retired": true,
    "profession_ids": ["teacher"],
    "profession_labels": ["Teacher"],
    "evidence": { "status": "supported", "quote": "She taught at Austin ISD for 31 years.", "flags": [] }
  }],
  "military": {
    "veteran": { "status": "supported", "quote": "He served in the U.S. Army during Vietnam.", "flags": [] },
    "branches": [{ "value": "Army", "status": "supported", "quote": "...", "flags": [] }],
    "eras": [{ "value": "Vietnam War", "status": "supported", "quote": "...", "flags": [] }]
  },
  "education": [{ "school": "University of Texas", "level": "bachelor", "year": 1971 }],
  "places": { "birthplace": { "city": "Waco", "state": "TX" }, "residence": { "city": "Austin", "state": "TX" } }
}

Family Insights (include_survivors, beta)

Family Insights reads the named survivors listed in a matched obituary. Every verify response carries a top-level family block; how names are delivered depends on how Family Insights is set up on your account:

Inline — names are returned directly on match.survivors when you send include_survivors: true.
Unlock — the response reports whether named family is available (family.available, family.count) and returns family.unlock_url. Call POST /api/v1/verify/{verify_request_id}/family to receive the names. You are only charged when named people are delivered, once per obituary; if extraction is still running the call returns 202 with Retry-After and nothing is charged.
Not on your plan — extraction is skipped; family.status is not_offered and family.reason is family_not_enabled.

family block fields:

status — not_offered | ok | none_found | unavailable_realtime | error | null
available, count — whether named family was found, and how many
reason — unlock_required | not_available | no_named_family | family_not_enabled
notice_id, unlock_url — unlock accounts, when a match can be unlocked

Fields on match when names are delivered inline:

survivors — array of { name, relationship, location? }
survivors_status — ok | none_found | unavailable_realtime | error
survivors_source — obituary_full_text | snippet | scraped | null
survivors_beta — always true

When stored obituary text is missing or too short to list names, the API may fetch the obit page to parse survivors. That step can add about 10 seconds to response time. When text is unavailable or time runs out, the status is unavailable_realtime. Accuracy varies; use for research leads, not sole proof of heirship.

Batch verification

Verify up to 50 people per call with POST /api/v1/verify/batch. Each item uses the same schema as single verify; results return in request order with an index field.

The batch console accepts CSV columns including county, death_date, and optional include_survivors (via the heirs workflow toggle). Use Heirs lookup workflow (Beta) when your file comes from death records and you need obituary survivors — defaults to extended depth with a 10-year lookback.

See also API overview for batch metering and rate-limit behavior.

Data sources

Each lookup searches up to three layers (see search_scope flags):

Parsed obituaries — full-text obits from our indexing pipeline (source_trust: stored when matched)
Funeral-home listing inventory — names and direct obituary URLs from our funeral-home crawl (17,565+ enrolled sources; growing with daily and historical backfill)
Supplemental historical sources — additional obituary coverage when depth allows (source_trust: extended)

Coverage is strongest on enrolled funeral-home sites and recent deaths. It is not complete national coverage — regional gaps remain. not_found reflects the searched scope only.

match object (response)

Present on found and possible_match. Key fields:

The match field is always a JSON object (or null on not_found), regardless of search_depth. If you see a string, it was double-encoded on your side or from a legacy cache — parse it once or contact support.

matched_name, death_date, birth_date, location, obituary_url
source — publisher or funeral home name (nullable)
snippet — deprecated, always null. Obituary text is not delivered; open obituary_url to read the original
source_trust — stored | extended
evidence — name_match, location_match (includes county_state), dob_match
scoring_reasons — plain-language factors for this match
survivors, survivors_status, survivors_source, survivors_beta — when include_survivors was requested and Family Insights is delivered inline (beta)

Example request (auto — recommended)

Omit search_depth to let the API choose depth from stored inventory and DOB compatibility.

curl -X POST https://api.obituarymonitor.com/api/v1/verify \
  -H "Authorization: Bearer om_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jackie",
    "last_name": "Simmons",
    "dob": { "month": 11, "year": 1945 },
    "address": { "state": "TX" },
    "client_ref": "case-44201"
  }'

Example request (standard)

curl -X POST https://api.obituarymonitor.com/api/v1/verify \
  -H "Authorization: Bearer om_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Margaret",
    "last_name": "Henderson",
    "dob": { "month": 3, "year": 1942 },
    "address": { "city": "Austin", "state": "TX" },
    "search_depth": "standard",
    "client_ref": "case-88421"
  }'

Example request (county + heirs, extended)

Typical death-record / heir lookup: county + state (no city), known death date, extended lookback, and survivors extraction.

curl -X POST https://api.obituarymonitor.com/api/v1/verify \
  -H "Authorization: Bearer om_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Robert",
    "last_name": "Martinez",
    "address": { "state": "TX", "county": "Travis" },
    "death_date": "2014-08-22",
    "search_depth": "extended",
    "lookback_years": 10,
    "include_survivors": true,
    "client_ref": "tx-heir-001"
  }'

Example request (extended + lookback_years)

Use lookback_years to reach older deaths in stored inventory and web search. With lookback_years: 6 in 2026, web fan-out covers calendar years 2026 through 2021, and stored sources use a ~6-year death-date window. Check lookback_check.status for matches whose death falls before the window.

curl -X POST https://api.obituarymonitor.com/api/v1/verify \
  -H "Authorization: Bearer om_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Thomas",
    "last_name": "Plaskett",
    "dob": { "year": 1945 },
    "address": { "state": "PA" },
    "search_depth": "extended",
    "lookback_years": 6,
    "client_ref": "case-99102"
  }'

Example: found

{
  "result": "found",
  "confidence": 0.92,
  "review_recommended": false,
  "scoring_reasons": [
    "Stored index candidate",
    "Last name match",
    "Exact first name match",
    "State match (TX)",
    "City match: Austin",
    "stored_candidate_meets_found_threshold"
  ],
  "client_ref": "case-88421",
  "search_scope": {
    "stored_obituaries_checked": true,
    "listing_inventory_checked": true,
    "historical_web_search_checked": true,
    "search_depth": "standard",
    "search_depth_requested": "standard",
    "search_depth_auto_reason": null,
    "years_searched": [2025, 2026],
    "lookback_years_requested": null,
    "lookback_years_applied": null,
    "web_search_status": "completed"
  },
  "external_queries_count": 2,
  "checked_at": "2026-06-08T14:22:11.000Z",
  "match": {
    "matched_name": "Margaret Ann Henderson",
    "death_date": "2026-05-12",
    "birth_date": "1942-03-01",
    "location": "Austin, TX",
    "obituary_url": "https://example.com/obit/margaret-henderson",
    "source": "Example Funeral Home",
    "snippet": null,
    "source_trust": "stored",
    "evidence": {
      "name_match": "exact",
      "location_match": "city_state",
      "dob_match": "year_only"
    },
    "survivors": [
      { "name": "James Henderson", "relationship": "son", "location": "Austin, TX" },
      { "name": "Sarah Henderson", "relationship": "daughter" }
    ],
    "survivors_status": "ok",
    "survivors_source": "obituary_full_text",
    "survivors_beta": true,
    "scoring_reasons": [
      "Stored index candidate",
      "Last name match",
      "Exact first name match",
      "State match (TX)"
    ]
  },
  "candidates": []
}

Example: possible_match

{
  "result": "possible_match",
  "confidence": 0.68,
  "review_recommended": true,
  "scoring_reasons": [
    "External search candidate (lower trust)",
    "Last name match",
    "Exact first name match",
    "State match (TX)",
    "External trust penalty (-12)",
    "web_candidate_downgraded_to_possible_match"
  ],
  "client_ref": "case-88421",
  "search_scope": {
    "stored_obituaries_checked": true,
    "listing_inventory_checked": true,
    "historical_web_search_checked": true,
    "search_depth": "standard",
    "search_depth_requested": null,
    "search_depth_auto_reason": "dob_unconfirmed_staged_web",
    "years_searched": [2026, 2025],
    "lookback_years_requested": null,
    "lookback_years_applied": null,
    "stored_name_match_count": 0,
    "has_dob_compatible_stored_match": false,
    "web_search_status": "completed"
  },
  "external_queries_count": 3,
  "checked_at": "2026-06-08T14:22:11.000Z",
  "match": {
    "matched_name": "John Smith",
    "death_date": null,
    "location": "Dallas, TX",
    "obituary_url": "https://example.com/obit/john-smith-dallas",
    "source": "example.com",
    "snippet": null,
    "source_trust": "extended",
    "evidence": {
      "name_match": "exact",
      "location_match": "state_only",
      "dob_match": "unknown"
    },
    "scoring_reasons": [
      "External search candidate (lower trust)",
      "Last name match",
      "Exact first name match",
      "State match (TX)"
    ]
  },
  "candidates": [
    {
      "matched_name": "John Smith",
      "location": "Dallas, TX",
      "obituary_url": "https://example.com/obit/john-smith-dallas",
      "confidence": 0.68,
      "source_trust": "extended"
    }
  ]
}

Example: not_found

{
  "result": "not_found",
  "confidence": 0,
  "review_recommended": false,
  "not_proof_of_life": true,
  "interpretation": "No matching obituary was found in the searched sources for the provided identifiers. This is not proof the person is alive.",
  "negative_result_strength": "moderate",
  "scoring_reasons": ["no_qualifying_candidates"],
  "client_ref": "case-88421",
  "search_scope": {
    "stored_obituaries_checked": true,
    "listing_inventory_checked": true,
    "historical_web_search_checked": true,
    "search_depth": "standard",
    "search_depth_requested": null,
    "search_depth_auto_reason": "stored_coverage_sufficient",
    "years_searched": [],
    "lookback_years_requested": null,
    "lookback_years_applied": null,
    "web_search_status": "completed"
  },
  "external_queries_count": 1,
  "checked_at": "2026-06-08T14:22:11.000Z",
  "match": null,
  "candidates": []
}

Rate limits

Limits are configured per account: per-minute, daily, and monthly quotas. Extended-depth requests also respect a concurrent extended cap and a daily extended quota (max_extended_per_day).

Daily and extended-search quotas use a rolling 24-hour window (not calendar midnight). Each completed lookup in the last 24 hours counts toward the limit. The window is evaluated in UTC on our servers, so capacity frees continuously as older requests age out.

Extended-search requests (search_depth extended, or standard depth with a historical death date) also share a per-account max_extended_per_day cap. Only completed outcomes (found, possible_match, not_found) count — quota rejections and other errors do not.

429 — rate_limited or quota_exceeded
503 — extended_capacity (retry later)

Successful Verify responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, plus X-Quota-* headers when a monthly allotment applies. 429 and 503 responses include Retry-After. Idempotent replays may omit the rate-limit headers. You can also track usage on the developer Usage page or your account quotas on Overview.

Error responses

Errors use:

{ "error": { "code": "invalid_request", "message": "…" } }

HTTP	code	When
400	invalid_request	Validation failure (missing name, missing disambiguator, bad DOB, `lookback_years` without `extended`, etc.)
400	lookback_exceeds_quota	`lookback_years` exceeds account `max_lookback_years`
401	unauthorized	Missing or invalid API key
403	api_access_required	Key valid but API access not enabled on account
403	trial_expired	API trial period ended — contact support to continue
429	rate_limited / quota_exceeded	Account or key quota exceeded
503	extended_capacity	Extended search concurrency saturated
500	internal_error	Unexpected server error

Signed-in developers can test live requests in the test console and review volume charts in Usage.