# PrismClaim API

Hosted 837P claim verification. JWT required on all routes except Stripe webhook.

Base path: `/api/prismclaim/v1`

---

## POST /claims/verify

Verify a professional claim against clinical documentation.

**Auth:** `Authorization: Bearer <JWT>`

**Clinical note (storage-agnostic):** Send `clinical_note_text` **or** `clinical_note_uri`. Prefer a time-limited **HTTPS presigned URL** so PHI stays in customer storage (S3, Azure, GCS, MinIO, etc.). Hosted schemes: `https://`, `http://`, `s3://`, `gs://`, `file://` (dev when `PRISMCLAIM_ALLOW_FILE_URI=1`). Custom schemes: register adapters under `meeting-scheduler/prismclaim/storage/`.

**Graph-backed verify (PrismClinical):** Send `evidence_graph_id` + `as_of` (ISO date) instead of inline note. The engine loads the bitemporal slice, builds chunk-level evidence bindings, then runs the same policy pipeline. Optional `knowledge_time` pins transaction time for replay.

**Precedence:** `evidence_graph_id` + `as_of` → graph slice; else `clinical_note_text` / `clinical_note_uri`; else `422 NOTE_UNAVAILABLE`.

**Body (graph-backed example):**

```json
{
  "encounter_id": "enc_982431a",
  "evidence_graph_id": "egr_778899aabbcc",
  "as_of": "2026-08-19",
  "proposed_claim": {
    "encounter_id": "enc_982431a",
    "tenant_id": "tenant_42",
    "cpt_code": "27447",
    "icd10_code": "M17.12",
    "laterality": "LT",
    "units": 1,
    "date_of_service": "2026-08-19",
    "rendering_npi": "1234567890"
  },
  "input_mode": "PROPOSED"
}
```

**Body (inline text example):**

```json
{
  "encounter_id": "enc_982431a",
  "clinical_note_text": "Operative report: left knee arthroplasty ...",
  "proposed_claim": {
    "encounter_id": "enc_982431a",
    "tenant_id": "tenant_42",
    "cpt_code": "27447",
    "icd10_code": "M17.12",
    "laterality": "RT",
    "units": 1,
    "date_of_service": "2026-08-19",
    "rendering_npi": "1234567890"
  },
  "input_mode": "PROPOSED"
}
```

**Response (200):** `ClaimVerificationResponse` with `decision` (`ACCEPT` | `REVIEW` | `REFUSE`), `evidence_coverage`, `checks`, `violations`, `audit_manifest.claim_hash_v1`, optional `escalation_id`.

**Response (202):** Async ticket when verify exceeds sync threshold and note was loaded from a remote URI:

```json
{
  "status": "accepted",
  "ticket_id": "job_…",
  "poll_url": "/api/prismclaim/v1/jobs/job_…"
}
```

**Note fetch env (optional):** `PRISMCLAIM_NOTE_MAX_BYTES` (default 2MB), `PRISMCLAIM_NOTE_FETCH_TIMEOUT_S`, `PRISMCLAIM_NOTE_URI_ALLOWLIST_HOSTS` (comma-separated hosts for https), `PRISMCLAIM_ALLOW_FILE_URI` (local dev).

---

## GET /jobs/{ticket_id}

Poll async verification job.

---

## POST /claims/{claim_id}/replay

**Query:** `mode=historical` (default) or `mode=diagnostic&policy_version=latest`

Returns pinned historical response or diagnostic stub.

---

## POST /escalations/{escalation_id}/resolve

**Body:**

```json
{
  "resolver_id": "usr_9981a",
  "resolver_role": "SENIOR_BILLER",
  "action": "APPROVE_AS_IS",
  "justification": "Operative note confirms procedure.",
  "modified_claim_fields": null
}
```

Actions: `APPROVE_AS_IS`, `OVERRIDE_FIELD`, `REJECT_PERMANENTLY`. Creates `claim_hash_v2` on clearance.

---

## GET /claims/{claim_id}/audit-bundle

Export JSON audit package for payer review.

---

## GET /me

Subscriber plan, claims used this month, plan catalog.

---

## POST /checkout · POST /checkout/confirm · POST /webhook

Stripe billing (Developer $99/mo, Pro $499/mo). Same pattern as PrismSQL.

---

## MCP

Static tool descriptors in `/mcp_tools/` — agents call the **same REST API** with the **same auth** (JWT or `X-API-Key: pcl_…`). There is no separate MCP server process (same pattern as AntiSlop; PrismSQL is REST-only today).

| Tool | Descriptor | REST |
| --- | --- | --- |
| Verify | `prismclaim_verify.json` | `POST /v1/claims/verify` |
| Poll job | `prismclaim_get_job.json` | `GET /v1/jobs/{ticket_id}` |
| Batch | `prismclaim_batch_ingest.json` | `POST /v1/batches` |
| Ingest evidence | `prismclinical_ingest.json` | `POST /api/prismclinical/v1/evidence/ingest` |
| Query as-of | `prismclinical_query_as_of.json` | `POST /api/prismclinical/v1/evidence/query-as-of` |

Agent bootstrap: `/docs/prismclaim-agent-guide.md` · OpenAPI: `/docs/prismclaim-openapi.yaml`

---

## Diagnostic replay

`POST /claims/{claim_id}/replay?mode=diagnostic&policy_version=policy_v2.4.1` re-runs verification against a policy bundle without mutating the stored historical record. Requires the claim to have a stored verify request (claims verified after this release).

---

## Stack

PrismClaim-owned pipeline; VectorPrism, PrismManifest, Prism-Shield adapters optional (`PRISMCLAIM_SHIELD_ENABLED`). ChorusGraph optional for route ledger.

Docs: `prismclaim/docs/implementation-map.md`