Verify API reference: authentication, requests, and responses
Programmatic death verification via a single REST endpoint. Submit a name and location; receive
Public API documentation covers the Death Verification API (POST /api/v1/verify). For county-based daily obituary notice feeds, see Daily County Intelligence (GET /api/v1/county-feed/notices) or the product overview. For what the product does and how to get access, see the death verification API page.
Both responses can include biographical_profile: captured occupation and military service, each with an evidence status, plus education, places, and family counts when entitled, all stated in our own words (no obituary text or quotes). A confirmed occupation does not verify the other fields. Profession search is not included.
Professional monitoring integrations (ongoing obituary watches, match alerts, case management) are handled separately from the Verify API. Contact us for professional monitoring workflows.
POST /api/v1/verify
Production: https://api.obituarymonitor.com/api/v1/verify
See the full reference for request fields, search_depth, and response schema.
Include your API key in the Authorization header:
Authorization: Bearer om_live_xxxxxxxx
Keys are issued after API access is provisioned. API-primary customers use the developer portal to create keys and run test requests.
- Live vs test keys.
om_live_keys hit real data and count against quota.om_test_(sandbox) keys return deterministic fixtures with no quota, rate limit, or logging: ideal for CI. Sandbox responses include"sandbox": trueand anX-Sandboxheader; the outcome is keyed off the last-name initial (a, h → found, i, p → possible_match, q: z → not_found). - Expiry. Keys can be created with an expiry; expired keys return
401 key_expired. - Rotation. Rotating a key issues a replacement and keeps the old key valid for a 24h overlap so you can cut over without downtime.
- IP allowlist. Optionally restrict a key to specific IPs / CIDR ranges; off-list requests return
403 ip_not_allowed.
| Field | Required | Notes |
|---|---|---|
| first_name, last_name | Yes | Subject name |
| dob.month, dob.year, dob.day | No | Disambiguation; invalid values return 400. dob.day (requires month+year) enables exact-date matching. |
| death_date | No | Known/expected date of death: ISO YYYY-MM-DD/YYYY-MM/YYYY or {year, month?, day?}. A matching death date is a strong disambiguator and can confirm an otherwise-ambiguous common name. |
| address.city, address.state | No | Location disambiguator; 2-letter US state recommended. A free-form address.line1 ending in "City, ST" fills a missing city/state. |
| address.county | No | Optional disambiguator with address.state. Send the county name, not a county_slug. City is optional when county and state are both present. |
| search_depth | No | recent | standard | extended; omit for auto |
| client_ref | No | Your correlation id (echoed in response) |
| fresh | No | true bypasses the short web-search cache and forces a live fetch. (Single requests can also send a Cache-Control: no-cache header.) not_found results are never cached, so a newly published obituary is always picked up. |
Qualifying obituary match with sufficient confidence. Review match.evidence and scoring_reasons before automated action.
Partial or ambiguous signal. Review it before acting. review_recommended is typically true.
No qualifying obituary in searched scope. Includes not_proof_of_life: true. Absence of an obituary is not evidence the person is alive and is not a government death-registry result.
confidence is a 0 to 1 score reflecting match strength. negative_result_strength (weak / moderate / strong) applies to not_found only.
confidence_band is a calibrated label over confidence so you can route on a stable value instead of hard-coding thresholds:
high: confirmed match; safe for automated actionmoderate: strong signal; brief human review recommendedlow: weak/ambiguous; verify before actingnone:not_found(not proof of life)
Every match includes the source obituary so you can see why we matched. Calibrate confidence_band thresholds to your own risk tolerance. A not_found is never proof of life.
- Not a consumer report. ObituaryMonitor (Northgate Leland LLC) is not a consumer reporting agency and API output is not a consumer report under the FCRA. Do not use it for credit, insurance, employment, or housing eligibility.
- DPPA / GLBA. Results come from published obituaries and public web sources, no motor-vehicle (DPPA) or nonpublic financial (GLBA) data. You are responsible for lawful use in your jurisdiction.
- Not proof of life. A
not_foundis not a government death-registry result and not evidence the person is alive. - Retention. Per-request logs (normalized inputs + result, no full payload) power usage/billing; idempotency keys last 24h; the web-search cache is short-lived.
API customers attest to permissible use in the developer portal → Compliance.
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" },
"client_ref": "case-88421"
}'{
"result": "found",
"confidence": 0.92,
"confidence_band": "high",
"review_recommended": false,
"client_ref": "case-88421",
"match": {
"matched_name": "Margaret Ann Henderson",
"death_date": "2026-05-12",
"location": "Austin, TX",
"obituary_url": "https://example.com/obit/margaret-henderson"
}
}{
"result": "not_found",
"confidence": 0.0,
"confidence_band": "none",
"not_proof_of_life": true,
"interpretation": "No qualifying obituary was found in the searched scope.",
"negative_result_strength": "moderate",
"client_ref": "case-88421"
}Per-account limits: per-minute, daily, and monthly quotas. Extended-depth requests also respect a concurrent extended cap.
429:rate_limitedorquota_exceeded503:extended_capacity(retry later)
Successful Verify responses include throttle headers so you can pace requests:
X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset: per-minute ceiling, headroom, and reset (unix seconds)X-Quota-Limit/X-Quota-Remaining: monthly allotment (omitted when unlimited)Retry-After: seconds to wait, sent on429/503
Send an Idempotency-Key header (any unique string ≤255 chars) to make retries safe. If a network error leaves you unsure whether a request was charged, retry with the same key:
- Same key + identical body → the original response is replayed with
Idempotent-Replayed: trueand no additional quota usage. - Same key + different body →
422 idempotency_key_reuseon the Death Verification API. Daily County Intelligence uses409 idempotency_key_reusedfor the same situation. The two APIs differ until a future version. - Keys are retained for 24 hours.
Verify up to 50 people in a single call with POST /api/v1/verify/batch. Send { "items": [ ... ] } where each item is a normal verify request body (including address.county, death_date, and include_survivors: survivors parsing can add about 10 seconds per matched item).
- Results return in request order, each with its
index. - Each item is metered individually against your quota.
- Per-item failures appear as
{ index, error }instead of failing the whole batch. - If a rate/quota limit is hit mid-batch, remaining items return
rate_limitedandRetry-Afteris set.
Prefer a UI? The developer portal batch runner uploads a CSV and exports results. Enable Family Insights workflow (Beta) for death-record CSVs (county, death date, extended lookback, survivors).
For larger jobs (up to 5,000 names), use async POST /api/v1/verify/batch/jobs. Poll GET /api/v1/verify/batch/jobs/{job_id} (paginated when the job is large) or download .../export.csv. Rows are processed in the background.
Pull your account's verification history with GET /api/v1/requests for reconciliation, auditing, or your own dashboards.
- Filter by
result,search_depth,client_ref, andfrom/totimestamps. - Paginate with
limit(max 200) andoffset; the response includespagination.totalandhas_more. - Add
format=csvto download the page as CSV.
curl -H "Authorization: Bearer om_live_..." \ "https://api.obituarymonitor.com/api/v1/requests?result=found&limit=100"
When an async job from POST /api/v1/verify/batch/jobs finishes, we can POST a signed verify.batch.completed event so you don't have to poll. Register the event on a portal webhook endpoint under Integrations.
- Same signing as watches:
X-OM-Signature/X-OM-Event. - Payload
dataincludesjob_id, counts,export_url,poll_url, andduration_seconds.
Couldn't confirm a death yet? Register a watch and we'll keep re-verifying on a schedule, then POST a signed webhook the moment an obituary appears, no polling required.
curl -X POST https://api.obituarymonitor.com/api/v1/watches \
-H "Authorization: Bearer om_live_..." \
-H "Content-Type: application/json" \
-d '{
"first_name": "Margaret",
"last_name": "Henderson",
"address": { "state": "TX" },
"client_ref": "case-88421",
"webhook_url": "https://yourapp.com/hooks/obit"
}'- The response includes a one-time
secret: store it. Each delivery is signed withX-OM-Signature: t=<ts>,v1=<hmac-sha256>over"<ts>.<body>". - On a match we POST
{ event: "verify.watch.matched", watch_id, client_ref, data }and retry non-2xx responses with backoff. - Manage watches with
GET/POST /api/v1/watchesandGET/DELETE /api/v1/watches/{id}, or from the portal Watches page. - Confirm delivery from the developer portal test console before you go live.
| HTTP | code | When |
|---|---|---|
| 400 | invalid_request | Validation failure (missing disambiguator, bad DOB, etc.) |
| 400 | lookback_exceeds_quota | lookback_years exceeds account max_lookback_years |
| 401 | unauthorized | Missing or invalid API key |
| 403 | api_access_required | API access disabled on account |
| 403 | trial_expired | API trial expired |
| 429 | rate_limited / quota_exceeded | Quota exceeded |
| 503 | extended_capacity | Extended search concurrency saturated |
| 500 | internal_error | Unexpected server error |
Full error table and examples in the API reference.