Integration Guide

Welcome to CardioExplorer. This guide shows you how to integrate cardiac risk assessment capabilities into your healthcare platform.

Quick Start: Complete API Integration

Full API Integration Flow (Automated):

1. Authenticate → Get access token
2. Create Draft → Send FHIR data
3. Run Test → Trigger AI analysis
4. Get Results → Retrieve full report

Alternative: UI-Based Flow:

1. Authenticate → Get access token
2. Create Draft → Send FHIR data
3. Generate Magic Link → Healthcare provider reviews in CardioExplorer UI

Overview

CardioExplorer provides two authentication methods for different integration scenarios:

Organization Authentication: Server-to-server integration using OAuth 2.0

Magic Link Authentication: User-friendly authentication to access our platform using magic-link

Authentication Flow

Step 1: Get Organization Credentials

Contact our team at info@explorishealth.com to register your organization and receive:

clientId (UUID)

clientSecret (secure key)

Step 2: Authenticate Your Organization

POST /api/organization-auth/authenticate

Use your credentials (clientId and clientSecret) to call this api which will return you the bearer token.

Response:

{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600
  }
}

📖 View detailed documentation →

Step 3: Generate Magic Links for Your Users

POST /api/auth/magic-links/generate

Use your access token to create magic links for healthcare providers:

Response:

{
  "status": "success",
  "data": {
    "magicLink": "https://api.cardioexplorer.com/api/auth/magic-links/verify?token=generated_token",
    "expiresAt": "2024-01-25T11:30:00Z"
  }
}

📖 View detailed documentation →

Step 4: Direct Users to CardioExplorer

Send the magic link to your healthcare providers. When they click it, they'll be automatically logged into the CardioExplorer platform to perform cardiac risk assessments.

FHIR Integration

CardioExplorer supports FHIR (Fast Healthcare Interoperability Resources) integration, allowing you to create draft cardiac risk assessment tests directly from FHIR-compliant patient data.

Step 5: Generate Draft Test from FHIR Resource

POST /api/fhir/draft-test

Send a FHIR resource (Bundle, Observation, Patient, etc.) to automatically validate, extract relevant cardiac data, and create a draft test for review.

Prerequisites:

Valid access token from Step 2

FHIR-compliant JSON resource containing patient data

Request:

What happens server-side:

Validation: The FHIR resource is validated against FHIR standards

Extraction: Relevant cardiac risk factors are extracted and mapped to CardioExplorer concepts

Draft Creation: A draft test is created with the extracted data, ready for review

Success Response:

{
  "success": true,
  "draftTestId": "b4f1a1d4-0ef7-4f0e-9f34-2c3c5e4f6a10",
  "itemsMapped": 12
}

Error Responses:

Validation Failed:

{
  "success": false,
  "message": "validation failed",
  "validation": {
    "valid": false,
    "issues": [...]
  }
}

User Not Authenticated:

{
  "success": false,
  "message": "User not authenticated"
}

⚡ Choose Your Integration Path

After creating a draft test (Step 5), you have two options to proceed:

🌐 Option A: UI-Based Review (Magic Link Approach)

Use this when: Healthcare providers need to manually review, complete, or modify the draft test in the CardioExplorer interface.

Flow:

Step 5: Create Draft → Generate Magic Link (Step 3) → User reviews in UI → Complete & Get Results

Steps:

Create draft test from FHIR (Step 5) ✓

Generate magic link for the healthcare provider (Step 3)

Provider clicks the link and reviews the draft in CardioExplorer UI

Provider completes any missing fields and runs the assessment

Results are displayed in the CardioExplorer interface

Best for:

Cases requiring clinical review and validation

Incomplete FHIR data that needs manual completion

Healthcare providers who prefer visual interface

Training and educational purposes

🔧 Option B: Fully Automated API Workflow

Use this when: You want to fully automate the risk assessment without any manual intervention.

Flow:

Step 5: Create Draft → Step 6: Run Test via API → Step 7: Get Results via API

Steps:

Create draft test from FHIR (Step 5) ✓

Run cardiac risk assessment via API (Step 6) ⬅️ Continue here

Retrieve full patient report via API (Step 7)

⚠️ Important: This path requires that your FHIR bundle contains all required data fields. If data is incomplete, the API will return validation errors in Step 6.

Step 6: Run the Cardiac Risk Assessment (API Path)

POST /api/ccs/v1/tests/{id}/run

After creating a draft test, trigger the AI model to analyze the cardiac risk factors and calculate risk scores.

Request:

Success Response:

{
    "testId": "901804f2-566f-4dc4-af33-7beb6432073c",
    "patientId": "2307",
    "riskScore": 0.4990183413028717,
    "riskLevel": "High",
    "recommendation": "Coronary CT angiography (CCTA) for diagnosis and risk stratification is recommended",
    "completedAt": "2026-02-01T19:08:40.4233333",
    "warnings": []
}

Key Response Fields:

testId: The test ID (unique identifier for this assessment)

patientId: Patient identifier associated with this test

riskScore: Risk score between 0.0 (low risk) and 1.0 (high risk)

riskLevel: Human-readable risk level ("Very Low", "Low", "Moderate", "High", "Very High")

recommendation: Clinical recommendation based on risk assessment

completedAt: Timestamp when the test was completed (ISO 8601 format)

warnings: Array of warning messages (if any validation issues occurred)

Error Responses:

404 Not Found: Test ID doesn't exist or you don't have permission

400 Bad Request: Validation errors in the test data

401 Unauthorized: Access token expired or invalid

Step 7: Retrieve Full Patient Report (API Path)

GET /api/ccs/v1/tests/{id}/result

Get the complete cardiac risk assessment report with all biomarker data, risk analysis, and clinical recommendations.

Request:

Success Response:

{
  "testId": "b4f1a1d4-0ef7-4f0e-9f34-2c3c5e4f6a10",
  "patientInfo": {
    "patientId": "patient-123",
    "age": 48,
    "gender": "male"
  },
  "testDate": "2026-01-25T10:30:00Z",
  "riskAssessment": {
    "score": 0.342,
    "riskLevel": "Moderate",
    "riskClass": 1,
    "populationRiskLevel": "Above average"
  },
  "biomarkers": {
    "cholesterol": {
      "total": 220,
      "hdl": 45,
      "ldl": 150,
      "unit": "mg/dL"
    },
    "bloodPressure": {
      "systolic": 140,
      "diastolic": 90,
      "unit": "mmHg"
    },
    "glucose": {
      "value": 110,
      "unit": "mg/dL"
    }
  },
  "clinicalRecommendations": [
    "Consider lifestyle modifications including diet and exercise",
    "Schedule follow-up in 6 months",
    "Monitor blood pressure regularly"
  ],
  "medications": {
    "antiplateletTherapy": "Yes",
    "lipidLoweringTherapy": "Yes",
    "betaBlocker": "No"
  }
}

Integration Modes

CardioExplorer supports two integration approaches depending on your use case:

🔧 API-Only Integration (Recommended for Full Automation)

Use this when you want to fully automate the cardiac risk assessment process within your system.

Flow:

Authenticate → Create Draft → Run Test → Get Results

🌐 UI Integration (Recommended for Healthcare Provider Access)

Use this when you want healthcare providers to manually review and complete assessments in the CardioExplorer interface.

Flow:

Authenticate → Generate Magic Link → Provider completes assessment in UI

API Reference Summary

Endpoint	Method	Purpose	Auth Required
`/api/organization-auth/authenticate`	POST	Get access token	❌ No (uses clientId/secret)
`/api/fhir/draft-test`	POST	Create draft from FHIR	✅ Yes (Bearer token)
`/api/ccs/v1/tests/{id}/run`	POST	Run AI risk analysis	✅ Yes (Bearer token)
`/api/ccs/v1/tests/{id}/result`	GET	Get full report	✅ Yes (Bearer token)
`/api/auth/magic-links/generate`	POST	Create UI access link	✅ Yes (Bearer token)

Detailed API Documentation

Authentication Endpoints

Obtain Access Token - Get organization access token using OAuth 2.0

Generate Magic Link - Create authentication links for healthcare providers

FHIR Integration Endpoints

Create Draft Test from FHIR - Validate FHIR resource and create draft cardiac risk assessment test

Assessment Endpoints

Run Test - Execute AI model analysis on draft test

Get Test Results - Retrieve complete cardiac risk assessment results

Integration Guide

Quick Start: Complete API Integration#

Overview#

Authentication Flow#

Step 1: Get Organization Credentials#

Step 2: Authenticate Your Organization#

Step 3: Generate Magic Links for Your Users#

Step 4: Direct Users to CardioExplorer#

FHIR Integration#

Step 5: Generate Draft Test from FHIR Resource#

⚡ Choose Your Integration Path#

🌐 Option A: UI-Based Review (Magic Link Approach)#

🔧 Option B: Fully Automated API Workflow#

Step 6: Run the Cardiac Risk Assessment (API Path)#

Step 7: Retrieve Full Patient Report (API Path)#

Integration Modes#

🔧 API-Only Integration (Recommended for Full Automation)#

🌐 UI Integration (Recommended for Healthcare Provider Access)#

API Reference Summary#

Detailed API Documentation#

Authentication Endpoints#

FHIR Integration Endpoints#

Assessment Endpoints#

Quick Start: Complete API Integration

Overview

Authentication Flow

Step 1: Get Organization Credentials

Step 2: Authenticate Your Organization

Step 3: Generate Magic Links for Your Users

Step 4: Direct Users to CardioExplorer

FHIR Integration

Step 5: Generate Draft Test from FHIR Resource

⚡ Choose Your Integration Path

🌐 Option A: UI-Based Review (Magic Link Approach)

🔧 Option B: Fully Automated API Workflow

Step 6: Run the Cardiac Risk Assessment (API Path)

Step 7: Retrieve Full Patient Report (API Path)

Integration Modes

🔧 API-Only Integration (Recommended for Full Automation)

🌐 UI Integration (Recommended for Healthcare Provider Access)

API Reference Summary

Detailed API Documentation

Authentication Endpoints

FHIR Integration Endpoints

Assessment Endpoints