Death Verification API

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 console — upload a CSV for batch verify (heirs / death-record workflows)
• Usage — volume charts, result breakdown, recent request log
• API Keys — create and revoke keys (shown once at creation)

Account limits (max_lookback_years, monthly/daily quotas, extended concurrency) are configured by your administrator in api_customer_settings.

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.

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
• Serper hits on recognized 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.

Set include_survivors: true to request structured survivors parsed from the obituary text when a match is found. Response fields on match:

• 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, survivors_status is unavailable_realtime. Accuracy varies; use for research leads, not sole proof of heirship.

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.

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 (~18k 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.

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 — excerpt when available (nullable; common on web matches)
• 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 (beta)

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"
  }'

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"
  }'

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.

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"
  }'

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)

The verify endpoint returns limit errors in the JSON body. It does not currently emit X-RateLimit-* response headers — track usage in the developer Usage page or your account quotas on Overview.