MCO integration guide

This is the path for a health plan / MCO to connect InsuredAudit to the systems you already run. InsuredAudit deploys inside your environment (your cloud or data center, under your HIPAA controls); you feed it your utilization-management data and read back plain-English member explanations, government-guideline checks, and court-ready evidence.

1. Provision a tenant and an API key

Each MCO is its own tenant. An operator with the admin scope creates the tenant and mints a scoped key for your integration service account:

# Create the tenant
curl -X POST https://api.insuredaudit.com/v1/tenants \
  -H "Authorization: Bearer <admin_key>" \
  -H "Content-Type: application/json" \
  -d '{ "tenant_id": "acme-health", "name": "Acme Health Plan" }'

# Mint a least-privilege key for your feed
curl -X POST https://api.insuredaudit.com/v1/api-keys \
  -H "Authorization: Bearer <admin_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme-health",
    "name": "edi-feed",
    "scopes": ["events:write", "events:read"]
  }'

The api_key is returned once — store it in your secret manager. All requests carry it as X-Api-Key (or Authorization: Bearer) and the X-Tenant-Id header. See Authentication.

2. Send your data

You do not need to transform your data into a proprietary format. InsuredAudit ingests the standards you already produce, or accepts canonical JSON events directly.

A canonical event looks like this:

curl -X POST https://api.insuredaudit.com/v1/events \
  -H "X-Api-Key: <key>" -H "X-Tenant-Id: acme-health" \
  -H "Content-Type: application/json" \
  -d '{
    "event_family": "AUTHORIZATION",
    "event_type": "AUTHORIZATION_DECIDED",
    "member_id": "M-000123",
    "source_system": "UM_PLATFORM",
    "source_record_id": "AUTH-88291",
    "event_effective_timestamp": "2026-05-01T14:00:00Z",
    "outcome": "DENIED",
    "payload": {
      "service": "Skilled nursing",
      "procedure_codes": ["G0299"],
      "diagnosis_codes": ["E11.621"],
      "jurisdiction": "TX",
      "program": "Medicaid Managed Care",
      "carc": ["CO-50"],
      "rationale": "Medical necessity not established"
    }
  }'

Every event is appended to a tamper-evident, hash-chained ledger. See the event envelope.

3. Read back the advocacy + audit surface

Once data is flowing, your applications (and the member portal) can read:

• GET /v1/members/:id/timeline — the member’s full record.
• GET /v1/advocacy/explain/:event_id — the denial in plain English.
• GET /v1/advocacy/guideline/:event_id — does CMS / the published rule support approval?
• POST /v1/advocacy/recode/:event_id — re-coding + appeal guidance.
• POST /v1/bundles — a signed, court-ready evidence bundle.

4. Subscribe to webhooks (optional)

Register an HMAC-signed webhook to drive downstream automation when decisions, appeals, or denials land. See Webhooks.

curl -X POST https://api.insuredaudit.com/v1/webhooks \
  -H "X-Api-Key: <key>" -H "X-Tenant-Id: acme-health" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app/hooks/insuredaudit", "events": ["event.ingested","advocacy.verdict"] }'

Next: Quickstart · API reference · Authentication