AI Medical Tourism Platform API

Case Orchestration Clinic/Hospital B2B Network Quoting & Packages Eligibility & Document AI Scheduling & Teleconsult Messaging + Audit Trail Payments + Settlement Hooks Policy/Consent Controls
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

1) Quickstart

2) Core Objects

3) Case Workflow Model

Cases progress through explicit states. You can customize permitted transitions per tenant (operator), but the default model is designed to avoid “manual chaos” in cross-border coordination.

Key endpoints

4) AI Decision Endpoints (the “decision layer”)

These endpoints produce decisions you can automate against. Each response includes: confidence, reasons[], and trace_id.

Eligibility example

{
  "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"}
  ]
}

{
  "case_id":"case_10021",
  "eligibility":{
    "readiness_score":0.78,
    "confidence":0.88,
    "reasons":[
      {"code":"DOCS_PARTIAL","detail":"Missing imaging summary (if available)"},
      {"code":"TIMELINE_FEASIBLE","detail":"Preferred window feasible for matched providers"}
    ],
    "missing_documents":[
      {"type":"IMAGING_SUMMARY","priority":"MEDIUM","why":"Improves surgeon review quality"}
    ],
    "routing_flags":[
      {"flag":"TELECONSULT_RECOMMENDED","severity":"LOW"}
    ],
    "trace_id":"trace_elg_7f11c"
  }
}

5) Provider Network & Offer Catalog

Providers expose structured offers, policies, availability, and operational requirements. You can onboard clinics/hospitals via API or an internal portal—API is the source of truth.

6) Quotes, Packages & Policies

Quotes are case-specific, time-bounded, and policy-aware. This is the commercial core. The API supports itemized quotes or single-price packages.

Quote request example

{
  "tenant_id":"t_global_med",
  "case_id":"case_10021",
  "providers":["prov_tr_901","prov_mx_140","prov_th_333"],
  "requested_offer_types":["PACKAGE","ITEMIZED"],
  "policy":{"currency":"USD","consent":"GRANTED"},
  "commercial":{
    "payment_preference":"DEPOSIT",
    "deposit_max_usd":800
  }
}

7) Scheduling & Teleconsult

Scheduling must handle: time zones, provider capacity, patient availability, and teleconsult vs in-person mode. Appointments are first-class objects with participant roles and reschedule policies.

8) Secure Messaging & Audit

Medical travel requires a single source of truth for coordination. Messaging is case-scoped and auditable.

9) Webhooks

Webhooks deliver state changes and decisions to your systems reliably. Use signature verification + idempotency keys.

10) Auth, Security & Compliance Controls

11) Errors, Idempotency & Retries

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

12) Code Examples

cURL — Create a case

curl -sS https://api.spyface.com/v1/medical/cases \
  -H "Authorization: Bearer $SPYFACE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: case-create-10021" \
  -d '{
    "tenant_id":"t_global_med",
    "patient":{
      "external_patient_id":"ext_pat_771",
      "preferred_language":"EN",
      "country_of_origin":"GB"
    },
    "destination_preference":["TR","MX","TH"],
    "source":{"channel":"B2B_PARTNER","partner_id":"partner_01"}
  }'

Node.js — Run eligibility + trigger missing-doc tasks

const base = "https://api.spyface.com";
const headers = {
  "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
  "Content-Type": "application/json",
  "Idempotency-Key": "eligibility-case_10021"
};

const payload = {
  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" }
  ]
};

const res = await fetch(`${base}/v1/medical/ai/eligibility`, {
  method: "POST",
  headers,
  body: JSON.stringify(payload)
});
const out = await res.json();

if (out?.eligibility?.missing_documents?.length) {
  for (const d of out.eligibility.missing_documents) {
    await fetch(`${base}/v1/medical/cases/${payload.case_id}/tasks`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `task-${payload.case_id}-${d.type}`
      },
      body: JSON.stringify({
        tenant_id: payload.tenant_id,
        title: `Request ${d.type}`,
        priority: d.priority || "MEDIUM",
        owner_role: "COORDINATOR",
        state: "OPEN",
        metadata: { why: d.why, trace_id: out.eligibility.trace_id }
      })
    });
  }
}
console.log("Readiness:", out.eligibility.readiness_score, "Trace:", out.eligibility.trace_id);