AI Patient Readiness & Eligibility API

Clinical Workflow Scoring Document Completeness Contraindication Rules Routing Flags Provider-Specific Requirements Explainable Decisions Audit-Ready
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

1) Overview

“Eligibility” in medical tourism usually fails because intake is incomplete, documents are unstructured, and each provider has different pre-consult requirements. This API standardizes the process into a three-layer gating system:

2) Inputs: Intake + Documents

You can submit structured intake directly, or let the API derive fields from documents using document intelligence. Inputs are designed to be minimal, but extensible.

3) Outputs: Scores, Status, Flags

4) Scoring Model (Clinical Workflow Grade)

The readiness score is computed as a weighted composition of workflow-critical dimensions. You can customize weights per procedure family and per tenant.

5) Provider Rules & Contraindication Logic

Provider rules are explicit configuration—this is how you turn “clinic requirements” into machine-checkable gates. Rules are grouped by procedure and can include:

6) Checklists & Next-Best-Actions

Instead of telling users “missing docs,” the API returns a sequenced checklist that can drive your product UI and internal coordinator SOPs.

7) Endpoints

8) Webhooks

Use webhooks to drive automation (task creation, email/SMS triggers, clinic escalation). All webhooks should be verified by signature.

9) Security, Consent & Audit

10) Errors & Idempotency

{
  "error":{
    "code":"VALIDATION_ERROR",
    "message":"Missing required field: intake.procedure_code",
    "details":[{"path":"intake.procedure_code","reason":"REQUIRED"}],
    "request_id":"req_31b2"
  }
}

11) Code Examples

cURL — Readiness scoring

curl -sS https://api.spyface.com/v1/medical/ai/readiness \
  -H "Authorization: Bearer $SPYFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: readiness-case_10021" \
  -d '{
    "tenant_id":"t_global_med",
    "case_id":"case_10021",
    "policy":{"scope":"MEDICAL","consent":"GRANTED"},
    "intake":{
      "procedure_code":"PROC_RHINOPLASTY",
      "timeline":{"preferred_start":"2026-03-10","latest_start":"2026-04-15"},
      "constraints":{"budget_max_usd":5200,"language":"EN","destination":["TR","MX","TH"]}
    },
    "documents":[
      {"doc_id":"doc_aa1","type":"LAB_REPORT","hash":"sha256:...","language":"TR"},
      {"doc_id":"doc_aa2","type":"MEDICAL_HISTORY","hash":"sha256:...","language":"EN"}
    ]
  }'

Sample response — Clinical workflow-grade output

{
  "case_id":"case_10021",
  "readiness":{
    "readiness_score":0.74,
    "status":"NOT_READY",
    "confidence":0.90,
    "reasons":[
      {"code":"MISSING_DOC","detail":"Imaging summary not provided", "impact":"BLOCKING"},
      {"code":"DOC_FRESHNESS_OK","detail":"Lab report within expected range", "impact":"POSITIVE"}
    ],
    "missing_items":[
      {
        "type":"IMAGING_SUMMARY",
        "priority":"MEDIUM",
        "why":"Improves surgeon review quality and reduces back-and-forth",
        "blocking":true
      }
    ],
    "routing_flags":[
      {"flag":"TELECONSULT_RECOMMENDED","severity":"LOW","why":"Revision risk unknown from intake"}
    ],
    "checklist":[
      {"step":"REQUEST_DOCUMENT","target":"IMAGING_SUMMARY","owner_role":"COORDINATOR"},
      {"step":"SCHEDULE_TELECONSULT","owner_role":"COORDINATOR"}
    ],
    "trace_id":"trace_ready_22c9a"
  }
}

Python — Auto-create tasks from checklist

import os, requests, json

BASE = "https://api.spyface.com"
KEY  = os.environ["SPYFACE_API_KEY"]

def post(path, body, idem):
  return requests.post(
    f"{BASE}{path}",
    headers={
      "Authorization": f"Bearer {KEY}",
      "Content-Type": "application/json",
      "Idempotency-Key": idem
    },
    data=json.dumps(body),
    timeout=30
  ).json()

tenant_id = "t_global_med"
case_id   = "case_10021"

readiness = post("/v1/medical/ai/readiness", {
  "tenant_id": tenant_id,
  "case_id": case_id,
  "policy":{"scope":"MEDICAL","consent":"GRANTED"},
  "intake":{
    "procedure_code":"PROC_RHINOPLASTY",
    "timeline":{"preferred_start":"2026-03-10","latest_start":"2026-04-15"},
    "constraints":{"budget_max_usd":5200,"language":"EN","destination":["TR","MX","TH"]}
  },
  "documents":[
    {"doc_id":"doc_aa1","type":"LAB_REPORT","hash":"sha256:...","language":"TR"},
    {"doc_id":"doc_aa2","type":"MEDICAL_HISTORY","hash":"sha256:...","language":"EN"}
  ]
}, f"readiness-{case_id}")

chk = readiness.get("readiness", {}).get("checklist", [])
trace = readiness.get("readiness", {}).get("trace_id", "n/a")

for i, item in enumerate(chk):
  title = f"{item['step']}: {item.get('target','')}".strip()
  post(f"/v1/medical/cases/{case_id}/tasks", {
    "tenant_id": tenant_id,
    "title": title,
    "priority": "MEDIUM",
    "owner_role": item.get("owner_role","COORDINATOR"),
    "state": "OPEN",
    "metadata": {"trace_id": trace, "source": "ai_readiness"}
  }, f"task-{case_id}-{i}")

print("Created tasks from checklist. Trace:", trace)