API Documentation

Authentication

All API requests require authentication using an API key. Include your API key in theAuthorizationheader using the Bearer token format.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Interactive API Playground

Test API endpoints with sample data in our sandbox environment. No API key required for the playground. Responses shown are examples of what you'll receive from the live API.

API Endpoints

The following endpoints are available for managing watches and matches programmatically.

Rate Limits

API requests are rate-limited to ensure fair usage and system stability. Rate limits vary by plan tier. When you exceed the rate limit, the API returns a 429 Too Many Requests response.

X-RateLimit-Limit: 1000        # Maximum requests per minute
X-RateLimit-Remaining: 998     # Requests remaining in current window
X-RateLimit-Reset: 1705312800  # Unix timestamp when limit resets
Retry-After: 30                # Seconds to wait (only on 429)

SLA & Uptime Guarantees

ObituaryMonitor provides service level agreements (SLAs) based on your plan tier. Our infrastructure is designed for high availability with redundant systems across multiple availability zones.

Webhooks

{
  "event": "match.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_id": "wh_abc123",
  "signature": "sha256=...",
  "data": {
    "match_id": "m_abc123",
    "watch_id": "w_xyz789",
    "confidence_score": 0.94,
    "state_statute_ref": "Ohio Rev. Code § 2117.06",
    "decedent": {
      "full_name": "John A. Smith",
      "city": "Columbus",
      "state": "OH",
      "date_of_death": "2024-01-18"
    },
    "obituary": {
      "source": "Columbus Dispatch",
      "source_url": "https://..."
    }
  }
}

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const expected = `sha256=${expectedSignature}`;

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-obituarymonitor-signature'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(payload);
  // Process the webhook event...

  res.status(200).json({ received: true });
});

Error Handling

The API uses standard HTTP status codes to indicate success or failure of requests.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "first_name",
        "message": "First name is required"
      }
    ]
  },
  "request_id": "req_abc123xyz"
}

SDKs & Libraries

Official client libraries are available for popular programming languages to simplify integration. All SDKs handle authentication, rate limiting, and error handling automatically.

Quick Start Examples

import { ObituaryMonitor } from '@obituarymonitor/sdk';

// Initialize the client
const client = new ObituaryMonitor({
  apiKey: process.env.OBITUARYMONITOR_API_KEY,
});

// Create a new watch
const watch = await client.watches.create({
  firstName: 'John',
  lastName: 'Smith',
  city: 'Columbus',
  state: 'OH',
  aliases: ['Johnny Smith'],
  notes: 'Estate beneficiary - Monitor for probate',
});

console.log('Watch created:', watch.id);

// List all matches
const matches = await client.matches.list({
  status: 'pending',
  limit: 10,
});

for (const match of matches.data) {
  console.log(`Match: ${match.decedent.fullName} (Confidence: ${match.confidenceScore})`);
}

// Confirm a match
await client.matches.update(match.id, {
  status: 'confirmed',
  notes: 'Identity verified via SSN match',
});

// Export audit log
const exportResult = await client.matches.export({
  format: 'pdf',
  includeAudit: true,
});

console.log('Export ready:', exportResult.downloadUrl);