Technical Documentation

Developer Documentation

Complete technical specifications, API documentation, and integration guides for embedding SDOH Risk Intelligence into your EHR systems.

Quick Start

Get up and running in minutes

API Reference

Complete endpoint documentation

FHIR Integration

SMART on FHIR + Gravity

Security

FedRAMP, HIPAA, compliance

Getting Started

SDOH Risk integrates with Epic and Oracle Health (Cerner) via SMART on FHIR and CDS Hooks 2.0

Epic Integration

1. Register Your Application

  • Create Epic developer account at fhir.epic.com
  • Request SMART on FHIR sandbox access
  • Register your application with redirect URIs

2. Configure OAuth 2.0

  • Launch context: launch/patient
  • Scopes: patient/*.read patient/Observation.write
  • Token endpoint: https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token

3. Test in Sandbox

  • Use Epic sandbox patient IDs for testing
  • Validate FHIR R4 resource reads
  • Test CDS Hooks patient-view and order-select

Oracle Health Integration

1. Register Your Application

  • Create CernerCare account at developer.cerner.com
  • Access Code Console for sandbox testing
  • Register SMART application with client ID

2. Configure SMART Launch

  • Launch type: EHR Launch
  • FHIR version: R4 (Millennium Platform APIs)
  • Authorization: OAuth 2.0 with PKCE

3. Test in Code Console

  • Use Oracle Health sandbox environment
  • Validate FHIR DSTU2 and R4 compatibility
  • Test Gravity FHIR write-back rendering

API Reference

RESTful API endpoints for SDOH risk scoring, explainability, and recommendations

Base URL

Production: https://api.sdohrisk.com/v1
Sandbox: https://sandbox.sdohrisk.com/v1

Core Endpoints

POST/risk/calculate

Calculate composite SDOH risk score for a patient

Request Example
{
  "patient_id": "Patient/veteran-12345",
  "fhir_server": "https://fhir.epic.com/prod",
  "access_token": "Bearer eyJhbGc...",
  "include_drivers": true
}
Response Example
{
  "composite_risk": 78,
  "category": "HIGH",
  "drivers": [
    { "factor": "Housing Instability", "score": 85 },
    { "factor": "Food Insecurity", "score": 62 },
    { "factor": "Transportation", "score": 71 }
  ],
  "timestamp": "2025-10-02T14:30:00Z"
}
GET/risk/explain/:patient_id

Get explainable AI breakdown of risk factors with causal pathways

Response Example
{
  "patient_id": "Patient/veteran-12345",
  "explanations": [
    {
      "factor": "Housing Instability",
      "evidence": [
        "Eviction history (2 months behind rent)",
        "No stable address past 90 days",
        "ZIP code: high cost burden area (44102)"
      ],
      "causal_pathway": "Housing instability → Medication non-adherence → ED utilization"
    }
  ]
}
POST/recommendations/generate

Generate actionable referral recommendations based on risk profile

Response Example
{
  "recommendations": [
    {
      "category": "Housing",
      "action": "Refer to VA SSVF (Supportive Services for Veteran Families)",
      "priority": "HIGH",
      "expected_impact": "15% reduction in ED revisits",
      "fhir_resource": {
        "resourceType": "ServiceRequest",
        "code": { "text": "VA SSVF Referral" }
      }
    }
  ]
}

FHIR Integration

Standards-based integration using SMART on FHIR, CDS Hooks 2.0, and Gravity FHIR IG

SMART on FHIR

Our app launches within Epic and Oracle Health using the SMART on FHIR standard.

Required Scopes

  • launch/patient - Patient context
  • patient/Observation.read - Lab results, vitals
  • patient/Condition.read - Diagnoses
  • patient/Observation.write - SDOH risk scores
  • patient/ServiceRequest.write - Referrals

CDS Hooks 2.0

Real-time clinical decision support cards trigger at critical workflow moments.

Supported Hooks

  • patient-view - Chart open triggers
  • order-select - Medication/order entry
  • order-sign - Before finalizing orders

Card Types

  • ⚠️ Warning cards for high-risk patients
  • ℹ️ Info cards with actionable suggestions
  • ✅ Success cards for completed interventions

Gravity FHIR Implementation Guide

We use the HL7 Gravity FHIR IG for standardized SDOH data exchange and Z-code conditions.

SDOH Observations

{
  "resourceType": "Observation",
  "status": "final",
  "category": [{
    "coding": [{
      "system": "http://hl7.org/fhir/us/sdoh-clinicalcare/...",
      "code": "sdoh-category-unspecified"
    }]
  }],
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "96777-8",
      "display": "AHC HRSN screening tool"
    }]
  },
  "valueInteger": 78
}

Z-Code Conditions (ICD-10)

  • Z59.0 - Homelessness
  • Z59.1 - Inadequate housing
  • Z59.4 - Lack of adequate food
  • Z59.7 - Insufficient social insurance
  • Z60.2 - Problems living alone

Security & Compliance

Enterprise-grade security with federal healthcare compliance built-in

FedRAMP Ready

AWS GovCloud IL-4/5 infrastructure with FedRAMP Moderate controls implemented

HIPAA Compliant

BAA available, PHI encryption at rest and in transit, comprehensive audit logging

FedMCP Audit

Cryptographic proof of all AI decisions with tamper-evident audit trails

Security Features

Data Protection

  • • AES-256 encryption at rest
  • • TLS 1.3 for all data in transit
  • • FIPS 140-2 validated cryptographic modules
  • • PHI tokenization and de-identification
  • • Automated key rotation (90 days)

Access Controls

  • • OAuth 2.0 / OpenID Connect authentication
  • • Role-based access control (RBAC)
  • • Multi-factor authentication (MFA) enforced
  • • Session timeout (15 minutes idle)
  • • Principle of least privilege

Audit & Monitoring

  • • Comprehensive audit logs (all API calls)
  • • Real-time anomaly detection
  • • CloudWatch + CloudTrail integration
  • • FedMCP cryptographic audit trail
  • • Compliance reporting dashboard

Infrastructure

  • • AWS GovCloud US-East/West regions
  • • Multi-AZ deployment for high availability
  • • DDoS protection (AWS Shield Advanced)
  • • WAF rules for API protection
  • • Automated vulnerability scanning

Support & Resources

We're here to help you succeed with SDOH Risk integration

Developer Portal

Interactive API explorer, code samples, and sandbox environment

Visit Portal →

Technical Support

24/7 support for production issues, SLA-backed response times

support@sdohrisk.com

System Status

Real-time API status, uptime monitoring, and incident reports

View Status →

Ready to Integrate?

Get sandbox access and start building with SDOH Risk Intelligence today

Request Demo