Getting Started with the API
Integrate ObituaryMonitor's death surveillance system into your application. This guide walks you through authentication, creating watches, and receiving real-time death notifications.
Prerequisites
- An ObituaryMonitor account with Professional 250+ plan (API access required)
- Basic understanding of REST APIs and HTTP requests
- A server or application to receive webhook notifications (optional)
Integration Overview
Create an Account
Sign up for ObituaryMonitor and choose a Professional plan with API access.
Generate API Key
Navigate to Settings → API Keys and create a new API key for your application.
Make Your First Request
Use your API key to authenticate and create your first watch programmatically.
Configure Webhooks
Set up webhook endpoints to receive real-time notifications when matches are found.
Authentication
All API requests require authentication using a Bearer token. Your API key identifies your account and enforces rate limits based on your subscription tier.
- 1Log in to your ObituaryMonitor dashboard
- 2Navigate to Settings → API Keys
- 3Click "Create New API Key" and give it a descriptive name
- 4Copy your key immediately — it won't be shown again
Security Warning
Never expose your API key in client-side code, public repositories, or browser console. Store it securely as an environment variable.
Making Authenticated Requests
Authorization: Bearer YOUR_API_KEY Content-Type: application/json
Storing Your API Key Securely
# ObituaryMonitor API Configuration OBITUARYMONITOR_API_KEY=om_live_xxxxxxxxxxxxxxxxxxxx OBITUARYMONITOR_API_URL=https://api.obituarymonitor.com/v1
Create Your First Watch
A watch monitors obituary sources for a specific person. When a potential match is found, you'll receive a notification via webhook or can poll the matches endpoint.
Create a Watch
curl -X POST "https://api.obituarymonitor.com/v1/watches" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"first_name": "John",
"last_name": "Smith",
"middle_name": "Robert",
"city": "Columbus",
"state": "OH",
"aliases": ["Johnny Smith", "J.R. Smith"],
"relatives": ["Mary Smith", "Robert Smith Jr."],
"notes": "Estate beneficiary - File #2024-001"
}'Response
{
"success": true,
"data": {
"id": "w_8f9a3b2c",
"first_name": "John",
"last_name": "Smith",
"middle_name": "Robert",
"city": "Columbus",
"state": "OH",
"status": "active",
"created_at": "2024-01-15T10:30:00Z"
},
"message": "Watch created successfully. Surveillance begins immediately."
}| Field | Type | Required | Description |
|---|---|---|---|
| first_name | string | Required | Person's first name |
| last_name | string | Required | Person's last name |
| middle_name | string | Optional | Middle name for better matching accuracy |
| city | string | Optional | City for location-based filtering |
| state | string | Optional | Two-letter state code (e.g., "OH") |
| aliases | string[] | Optional | Alternative names, nicknames, maiden names |
| relatives | string[] | Optional | Known relatives for confirmation matching |
| notes | string | Optional | Internal notes (case number, context) |
Retrieve Matches
When our system finds a potential obituary match for one of your watches, it creates a match record. You can poll for matches or receive them via webhooks.
List All Pending Matches
curl "https://api.obituarymonitor.com/v1/matches?status=pending&limit=20" \ -H "Authorization: Bearer YOUR_API_KEY"
Match Response Structure
{
"success": true,
"data": {
"matches": [
{
"match_id": "m_abc123",
"watch_id": "w_8f9a3b2c",
"confidence_score": 0.94,
"status": "pending",
"created_at": "2024-01-20T08:45:00Z",
"decedent": {
"full_name": "John Robert Smith",
"age": 78,
"city": "Columbus",
"state": "OH",
"date_of_death": "2024-01-18"
},
"obituary": {
"source": "Columbus Dispatch",
"source_url": "https://www.legacy.com/obituaries/...",
"funeral_home": "Smith Family Funeral Home"
},
"reasons": [
"Exact name match: John Robert Smith",
"Location match: Columbus, OH",
"Relative match: Mary Smith (spouse)"
]
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"has_more": false
}
}
}Each match includes a confidence score (0.0 to 1.0) indicating match likelihood:
Strong match with multiple confirming factors
Probable match requiring verification
Potential match, review recommended
Configure Webhooks (Optional)
Instead of polling the API, configure webhooks to receive real-time notifications when matches are found. This is the recommended approach for production integrations.
Register a Webhook Endpoint
curl -X POST "https://api.obituarymonitor.com/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/obituary-monitor",
"events": ["match.created", "match.confirmed"],
"secret": "your_webhook_secret_for_signature_verification"
}'Webhook Payload Example
{
"event": "match.created",
"timestamp": "2024-01-20T08:45:00Z",
"webhook_id": "wh_xyz789",
"data": {
"match_id": "m_abc123",
"watch_id": "w_8f9a3b2c",
"confidence_score": 0.94,
"decedent": {
"full_name": "John Robert Smith",
"city": "Columbus",
"state": "OH",
"date_of_death": "2024-01-18"
},
"state_statute_ref": "Ohio Rev. Code § 2117.06"
}
}Webhook Security
Always verify webhook signatures using your secret before processing payloads. See the webhook signature verification guide for implementation examples.
Common Use Cases
Probate & Estate Attorneys
Automate beneficiary death monitoring for estate administration. Integrate with your case management system.
- Bulk import from case files
- Automatic PDF audit logs
- Court-ready documentation
Financial Institutions
Monitor account holders and beneficiaries for regulatory compliance and fraud prevention.
- Real-time death alerts
- Batch processing
- Compliance audit trails
Insurance Companies
Identify policyholder deaths for claims processing and policy updates.
- Policy holder monitoring
- Beneficiary notifications
- Claims automation
Healthcare & Medicare
Track patient mortality for care coordination and program compliance.
- HIPAA-compliant logging
- Care transition alerts
- Program reconciliation