Guides
API References
Guides
API References
  1. Guides
  • Guides
    • Integration Guide
    • FHIR Client Integration Guide
  1. Guides

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
5. Generate PDF → Download formatted report (optional)
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.
Key Features:
✅ Automatic FHIR validation - Validates resources against FHIR standards
✅ Intelligent data extraction - Maps FHIR observations to cardiac risk factors
✅ Gap analysis - Identifies missing and rejected items from 32 required fields
✅ Localized recommendations - Supports multiple languages (English, German) for clinical guidance

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:
1.
Validation: The FHIR resource is validated against FHIR standards
2.
Extraction: Relevant cardiac risk factors are extracted and mapped to CardioExplorer concepts
3.
Draft Creation: A draft test is created with the extracted data, ready for review
4.
Gap Analysis: System identifies which required fields are missing and which were rejected during mapping
Success Response:
{
    "success": true,
    "draftTestId": "29b2b745-6ba9-4e1f-9512-91247359eefb",
    "itemsMapped": 29,
    "itemsRejected": 1,
    "itemsMissing": 2,
    "rejectedItems": [
        {
            "conceptId": 3006923,
            "conceptName": "alat",
            "code": "1742-6",
            "vocabularyId": "LOINC",
            "resourceType": "Observation",
            "rejectionReason": "Data too old: 124.4 days (max: 90 days)",
            "entryUrl": "urn:uuid:857ea484-91af-4748-8f04-8858cbc1859f",
            "valueNumber": 49,
            "valueText": null,
            "unit": "U/L"
        }
    ],
    "missingItems": [
        {
            "conceptId": 40769783,
            "name": "High-sensitivity troponin T"
        },
        {
            "conceptId": 3016417,
            "name": "Pancreatic amylase"
        }
    ]
}
Response Field Details:
success: Boolean indicating if the draft was created successfully
draftTestId: UUID of the created draft test
itemsMapped: Count of successfully mapped FHIR data elements (12)
itemsRejected: Count of items that were rejected during processing (e.g., data too old, invalid values) (2)
itemsMissing: Count of required fields not found in the FHIR bundle (18)
rejectedItems: Array of rejected items with conceptId and name only (no displayName, internalName, or description)
missingItems: Array of missing required fields with conceptId and name only
Note on Required Fields: CardioExplorer requires 32 specific data points for a complete cardiac risk assessment. The response shows which of these are successfully mapped, which were rejected (present but invalid), and which are completely missing from your FHIR data.
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:
1.
Create draft test from FHIR (Step 5) ✓
2.
Review the missingItems and rejectedItems arrays in the response to understand data gaps
3.
Generate magic link for the healthcare provider (Step 3)
4.
Provider clicks the link and reviews the draft in CardioExplorer UI
5.
Provider completes any missing fields and runs the assessment
6.
Results are displayed in the CardioExplorer interface
Best for:
Cases requiring clinical review and validation
Incomplete FHIR data that needs manual completion (use missingItems to identify gaps)
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:
1.
Create draft test from FHIR (Step 5) ✓
2.
Run cardiac risk assessment via API (Step 6) ⬅️ Continue here
3.
Retrieve full patient report via API (Step 7)
⚠️ Important: This path requires that your FHIR bundle contains all required data fields. The draft creation response (Step 5) includes gap analysis showing missingItems and rejectedItems - use this to identify incomplete data before proceeding to Step 6. 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:
Query Parameters:
language (optional): Language code for localized clinical recommendations and risk level display. Supported values:
en (English) - Default if not specified
de (German)
When specified, both the recommendation and riskLevel fields in the response will be translated to the requested language.
Risk Level Translations:
English: "Very Low", "Low", "Moderate", "High", "Very High"
German: "Sehr niedrig", "Niedrig", "Mäßig", "Hoch", "Sehr hoch"
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": []
}
German Response Example (language=de):
{
    "testId": "901804f2-566f-4dc4-af33-7beb6432073c",
    "patientId": "2307",
    "riskScore": 0.4990183413028717,
    "riskLevel": "Hoch",
    "recommendation": "Koronare CT-Angiographie (CCTA) zur Diagnose und Risikostratifizierung wird empfohlen",
    "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 (localized based on language parameter)
English: "Very Low", "Low", "Moderate", "High", "Very High"
German: "Sehr niedrig", "Niedrig", "Mäßig", "Hoch", "Sehr hoch"
recommendation: Clinical recommendation based on risk assessment and ESC guidelines (localized based on language parameter)
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"
  }
}

Step 8: Generate PDF Report (API Path)#

GET /api/ccs/v1/tests/{ccsTestId}/report
Generate a PDF report for a specific CCS test and receive it as a base64-encoded string. This endpoint is ideal when you need to embed the PDF in your application or send it via API to downstream systems.
Request:
Query Parameters:
language (optional): Language locale for the PDF report. Supported values:
en-GB (English - UK) - Default if not specified
de-DE (German - Germany)
Success Response:
{
  "status": "success",
  "message": "PDF report generated successfully",
  "pdfContent": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...",
  "ccsTestId": "b4f1a1d4-0ef7-4f0e-9f34-2c3c5e4f6a10",
  "filename": "CardioExplorer_Report_b4f1a1d40ef74f0e9f342c3c5e4f6a10_20260125.pdf"
}
Response Field Details:
status: Status of the PDF generation ("success" or "error")
message: Human-readable message describing the result
pdfContent: Base64-encoded PDF file content
ccsTestId: The test ID for which the report was generated
filename: Suggested filename for the PDF (format: CardioExplorer_Report_{testId}_{date}.pdf)
Error Responses:
400 Bad Request - Test has no results:
{
  "status": "error",
  "message": "Test has no results",
  "ccsTestId": "b4f1a1d4-0ef7-4f0e-9f34-2c3c5e4f6a10",
  "errors": ["Cannot generate report for a test without results. Please run the test first."]
}
401 Unauthorized - Invalid or missing authentication:
{
  "status": "error",
  "message": "User not authenticated properly",
  "ccsTestId": "b4f1a1d4-0ef7-4f0e-9f34-2c3c5e4f6a10",
  "errors": ["Authentication required"]
}
403 Forbidden - Access denied to this test:
{
  "status": "error",
  "message": "Access denied",
  "ccsTestId": "b4f1a1d4-0ef7-4f0e-9f34-2c3c5e4f6a10",
  "errors": ["You don't have permission to access this test"]
}
404 Not Found - Test doesn't exist:
{
  "status": "error",
  "message": "CCS Test not found",
  "ccsTestId": "b4f1a1d4-0ef7-4f0e-9f34-2c3c5e4f6a10",
  "errors": ["The specified CCS test does not exist"]
}
Usage Example:

Step 9: Download PDF Report (API Path - Alternative)#

GET /api/ccs/v1/tests/{ccsTestId}/report/download
Generate and directly download a PDF report for a specific CCS test. This endpoint returns the PDF file directly (Content-Type: application/pdf) with appropriate headers for browser download.
Request:
Query Parameters:
language (optional): Language locale for the PDF report. Supported values:
en-GB (English - UK) - Default if not specified
de-DE (German - Germany)
Success Response:
Status Code: 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="CardioExplorer_Report_{testId}_{date}.pdf"
Body: Binary PDF file
Error Responses:
400 Bad Request: "Cannot generate report for a test without results. Please run the test first."
401 Unauthorized: "User not authenticated properly"
403 Forbidden: "You don't have permission to access this test"
404 Not Found: "CCS Test not found"
500 Internal Server Error: "An unexpected error occurred while generating the report"
Usage Example:
When to use each endpoint:
Use /report (Step 8) when you need:
To process the PDF programmatically
To send the PDF via email or other API
To store the PDF in your database or cloud storage
To embed the PDF in your application UI
Use /report/download (Step 9) when you need:
Direct browser download functionality
Simple download links in web applications
Minimal client-side processing

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 → Generate PDF Report

🌐 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#

EndpointMethodPurposeAuth Required
/api/organization-auth/authenticatePOSTGet access token❌ No (uses clientId/secret)
/api/fhir/draft-testPOSTCreate draft from FHIR with gap analysis (missing/rejected items)✅ Yes (Bearer token)
/api/ccs/v1/tests/{id}/run?language=enPOSTRun AI risk analysis with localized risk level and recommendations✅ Yes (Bearer token)
/api/ccs/v1/tests/{id}/resultGETGet full report✅ Yes (Bearer token)
/api/ccs/v1/tests/{id}/report?language=en-GBGETGenerate PDF report (base64)✅ Yes (Bearer token)
/api/ccs/v1/tests/{id}/report/download?language=en-GBGETDownload PDF report (file)✅ Yes (Bearer token)
/api/auth/magic-links/generatePOSTCreate 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

Report Generation Endpoints#

Generate PDF Report - Generate PDF report and receive as base64-encoded string
Download PDF Report - Download PDF report file directly
Modified at 2026-04-07 10:48:44
Next
FHIR Client Integration Guide
Built with