API Documentation

Clinical Intelligence API

PrecisionMD ingests one or more FHIR R4/R5 documents, de-duplicates them, resolves whether they belong to the same patient, and evaluates medical necessity against proprietary and public guidelines. Optimized for clinical decision support (CDS) and auditable, citation-backed determinations.

Authentication & Billing

All API requests must include your API Key in the x-api-key HTTP header. Billing is metered per unique document at $0.10 / document. Exact duplicates within a request are detected and never billed.

# Example Header
x-api-key: pmd_live_xxxxxxxxxxxx

Evaluate Documents

POST/api/evaluate

Accepts a single FHIR Bundle, or an array of bundles for multi-document ingestion. The engine parses each document, removes exact duplicates, runs patient identity resolution, and (only when records share a strong identifier) merges them into one clinical timeline before evaluating. Supported resources include Patient, Condition, Observation, MedicationRequest, DiagnosticReport, and Encounter.

Single Bundle

{ "fhirBundle": { ... } }

Multiple Documents

{ "documents": [ {...}, {...} ] }

Raw Array

[ {...}, {...} ]

Single Document

curl -X POST https://api.precisionmd.io/api/evaluate \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"fhirBundle\": $(cat patient1.json)}"

Multiple Documents

curl -X POST https://api.precisionmd.io/api/evaluate \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"documents\": [$(cat visit1.json), $(cat visit2.json)]}"

Duplicate documents are detected automatically and excluded from billing.

Response Object

{
  "audit_trace_id": "8f3e-42c1-9b12-a55...",
  "grounded": true,
  "ingestion": {
    "documentsUploaded": 3,
    ...
  },
  "identityResolution": {
    "status": "AUTO_MERGED",
    ...
  },
  "evaluations": [
    {
      "status": "Approved",
      ...
      },
      "grounded": true
    }
  ]
}

Identity Resolution States

AUTO_MERGED

Records share a strong identifier (MRN, enterprise ID). Merged into one timeline and evaluated together.

CANDIDATE_MATCH

Demographic similarity only. NOT merged — each document is evaluated independently and flagged for human confirmation.

DISTINCT_PATIENTS

Conflicting identity evidence (e.g. different DOB). Treated as separate patients, evaluated independently.

INSUFFICIENT_IDENTITY_DATA

No Patient resource present. No same-patient claim is made; documents are evaluated independently.

The PrecisionMD /api/evaluate endpoint leverages a multi-stage RAG pipeline. Submitted documents are cross-referenced against active clinical guidelines in real time, producing a Grounded Rationale with specific citations from clinical literature and payer policies. When grounding evidence is thin, the engine lowers its necessity score and abstains rather than fabricating a determination — the transparency required for high-stakes environments where black-box logic is not an option.

System Status Codes

200

Success

401

Auth Error

402

Trial Exhausted

422

Invalid FHIR

500

Engine Fail