Daily County Intelligence

1. Pull or filter with GET https://api.obituarymonitor.com/api/v1/county-feed/notices (optional state, county_slug, q). Never debits tokens.
2. Fetch one notice with GET …/notices/{id}. May enqueue preparation; never debits.
3. Request Family Extraction with POST …/family-extractions/batch (up to 50) or the single-notice path POST …/notices/{id}/family-extraction — the only token-authorization actions (same service as Family Explorer).
4. Poll GET …/survivors/updates (or batch / request status) until terminal readiness, then unlock again (idempotent) or GET detail for names.

• Max 50 unique notice_id values per request (empty_batch / batch_too_large / duplicate_notice_id → 400).
• Idempotency-Key required — same key + same items replays; same key + different payload → 409 idempotency_key_reused.
• Partial 200 — HTTP 200 on successful registration even when some items are rejected; inspect items[].error.
• Item-weighted writes — each item costs one write unit; 429 responses include X-RateLimit-Policy: write.
• No sync extract — the batch only registers requests; poll GET …/family-extractions/batches/{batch_id} or per-item request_id for status (read-only, no names).

curl -sS -X POST "https://api.obituarymonitor.com/api/v1/county-feed/family-extractions/batch" \
  -H "Authorization: Bearer om_live_YOUR_KEY" \
  -H "Idempotency-Key: batch-2026-09-25-001" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "notice_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1" },
      { "notice_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbb2" }
    ]
  }'

POST https://api.obituarymonitor.com/api/v1/county-feed/family-extractions/batch
Authorization: Bearer om_live_YOUR_KEY
Idempotency-Key: batch-2026-09-25-001
Content-Type: application/json

{
  "items": [
    { "notice_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1" },
    { "notice_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbb2" }
  ]
}

Partial success (HTTP 200)

{
  "batch_id": "batch_cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "submission_status": "completed",
  "submitted": 2,
  "accepted": 1,
  "rejected": 1,
  "created_at": "2026-09-25T12:00:00.000Z",
  "updated_at": "2026-09-25T12:00:01.000Z",
  "completed_at": "2026-09-25T12:00:01.000Z",
  "items": [
    {
      "position": 0,
      "notice_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
      "request_id": "req_dddddddd-dddd-4ddd-8ddd-dddddddddddd",
      "status": "pending_extract",
      "token_status": "not_charged",
      "error": null
    },
    {
      "position": 1,
      "notice_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbb2",
      "request_id": null,
      "status": null,
      "token_status": "not_charged",
      "error": {
        "code": "unsupported_source",
        "message": "Family Extraction is unavailable for this source."
      }
    }
  ]
}

Poll batch status (read-only)

GET https://api.obituarymonitor.com/api/v1/county-feed/family-extractions/batches/batch_cccccccc-cccc-4ccc-8ccc-cccccccccccc
Authorization: Bearer om_live_YOUR_KEY

const BASE = "https://api.obituarymonitor.com/api/v1/county-feed";
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Idempotency-Key": "batch-2026-09-25-001",
  "Content-Type": "application/json",
};

// Max 50 unique notice_ids. HTTP 200 includes partial success — check items[].error.
const batch = await fetch(`${BASE}/family-extractions/batch`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    items: noticeIds.map((notice_id) => ({ notice_id })),
  }),
}).then(async (r) => {
  if (r.status === 429) throw new Error("write rate limit — check X-RateLimit-Policy: write");
  if (r.status === 409) throw new Error("idempotency_key_reused with a different payload");
  if (!r.ok) throw new Error(`batch failed: ${r.status}`);
  return r.json(); // 200 even when some items were rejected
});

// Read-only poll — no side effects, no names
const status = await fetch(
  `${BASE}/family-extractions/batches/${batch.batch_id}`,
  { headers: { Authorization: headers.Authorization } }
).then((r) => r.json());

• source_type: "funeral_home" — full lifecycle: unlock, pending, settle, names.
• source_type: "newspaper" — reported as survivors_status: "unavailable" with survivors_unsupported_reason. An unlock returns unsupported_source: nothing is queued, no pending request is created, and no token is authorized.

A newspaper notice that already carries a settled result keeps serving it — support is withheld for new extraction work, not for data that already exists.

An explicit Family Extraction request is a billable action and is queued ahead of background warming, including trial warm-ahead. Browsing and watch-list traffic stay below it, so paging through search results never displaces someone else's readiness work.

• Explicit Family Extraction request — highest priority. A published completion target will follow once real queue execution has been measured; we are not quoting a time from queue position alone.
• Watch-list and detail interest — best effort, deliberately no SLA.
• Daily caps — each account has a daily ceiling on unlocks and on background interest. Exceeding it returns no queued work rather than degrading extraction for everyone.

• Not charged: GET pull, GET detail, GET survivors/updates; pending unlock interest; unavailable; unmetered accounts.
• Debited once: first successful unlock when settlement is billable (ok with named family members, or none_found).
• Not charged again: idempotent unlock when already entitled (already: true, newly_debited: false).
• Credited: terminal failure after a debit — compensating reversal; no permanent charge.
• Never charged: a source that does not support extraction (unsupported_source) — no queue entry and no authorization.
• There is no wallet reservation while pending — interest is recorded, debit happens only at settle.