Understanding Verify API Documentation

confidence is a 0–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 action
• moderate — strong lead; brief human review recommended
• low — weak/ambiguous; verify before acting
• none — not_found (not proof of life)

Internal benchmark, last run June 2026, against a 550-subject set: 500 known decedents drawn at random from our stored index plus 50 synthetic living controls, queried end-to-end through the live production API.

Methodology: recall is measured on subjects with a known obituary in scope; the false-positive rate is measured on living controls that must return not_found. Numbers describe this sample and depth config and are not a contractual guarantee — calibrate confidence_band thresholds to your own risk tolerance. A not_found is never proof of life.

• Not a consumer report. ObitWatch 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_found is 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.

Per-account limits: per-minute, daily, and monthly quotas. Extended-depth requests also respect a concurrent extended cap.

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

Every response includes throttle headers so you can pace requests without guessing:

• 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 on 429 / 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: true and no additional quota usage.
• Same key + different body → 422 idempotency_key_reuse.
• 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_limited and Retry-After is set.

Prefer a UI? The developer portal batch runner uploads a CSV and exports results. Enable Heirs lookup workflow (Beta) for death-record CSVs (county, death date, extended lookback, survivors).

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, and from/to timestamps.
• Paginate with limit (max 200) and offset; the response includes pagination.total and has_more.
• Add format=csv to download the page as CSV.

curl -H "Authorization: Bearer om_live_..." \
  "https://obituarymonitor.com/api/v1/requests?result=found&limit=100"

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://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 with X-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/watches and GET/DELETE /api/v1/watches/{id}, or from the portal Watches page.