API Endpoints

Overview & Getting Started

Resources

Agent CapabilitiesPrompt Best PracticesE-commerce IntegrationHealthcare Integration

Healthcare Integration Guide

Learn how to integrate SparkCo's AI agents into your healthcare practice for automated patient care management, wellness checks, and medication reminders.

Overview

This guide demonstrates how healthcare providers can use SparkCo to:

  • Conduct daily wellness checks
  • Send medication reminders
  • Schedule and confirm appointments
  • Follow up on care plans
  • Monitor patient progress

HIPAA Compliance

SparkCo is HIPAA-compliant and implements the following security measures:

  • End-to-end encryption for all communications
  • Secure storage of patient data
  • Access controls and audit logging
  • BAA (Business Associate Agreement) available
  • Regular security assessments

1. Patient Setup

Create recipients for your patients with relevant medical information:

// Create a new patient recipient
const patient = await createPatient({
  name: "John Doe",
  phone_number: "+1234567890",
  metadata: {
    medical_record_number: "MRN123456",
    primary_physician: "Dr. Smith",
    conditions: ["diabetes", "hypertension"],
    medications: [
      {
        name: "Metformin",
        dosage: "500mg",
        frequency: "twice daily",
        timing: ["09:00", "21:00"]
      }
    ],
    emergency_contact: {
      name: "Jane Doe",
      relationship: "Spouse",
      phone: "+1987654321"
    }
  }
});

// Set up care plan context
await updateContext(patient.id, {
  care_plan: {
    goals: ["blood_sugar_monitoring", "daily_exercise"],
    restrictions: ["low_sodium_diet"],
    monitoring_frequency: "daily"
  }
});

2. Configure AI Agents

Set up specialized agents for different care aspects:

// Create a medication reminder agent
const medicationAgent = await createAgent({
  name: "Medication Assistant",
  purpose: "Medication reminders and adherence monitoring",
  personality: "caring and persistent",
  knowledge_base: ["medication_guidelines.pdf", "side_effects.pdf"]
});

// Create a wellness check agent
const wellnessAgent = await createAgent({
  name: "Wellness Monitor",
  purpose: "Daily health checks and symptom monitoring",
  personality: "empathetic and thorough",
  knowledge_base: ["health_assessment.pdf", "emergency_protocols.pdf"]
});

// Create a care plan agent
const carePlanAgent = await createAgent({
  name: "Care Coordinator",
  purpose: "Care plan follow-up and progress tracking",
  personality: "supportive and encouraging",
  knowledge_base: ["care_guidelines.pdf", "lifestyle_recommendations.pdf"]
});

3. Set Up Automated Care

Medication Reminders

// Schedule medication reminders
async function scheduleMedicationReminders(patient) {
  const medications = patient.metadata.medications;
  
  for (const med of medications) {
    for (const time of med.timing) {
      await createRecurringReminder({
        recipient_id: patient.id,
        agent_id: medicationAgent.id,
        message: `Time to take your ${med.name} (${med.dosage}). 
                  Have you experienced any side effects?`,
        scheduled_time: time,
        repeat_rule: "daily"
      });
    }
  }
}

Daily Wellness Checks

// Schedule daily wellness calls
async function scheduleWellnessChecks(patient) {
  // Morning check-in
  await createSchedule({
    recipient_id: patient.id,
    agent_id: wellnessAgent.id,
    scheduled_time: "09:00",
    repeat_rule: "daily",
    purpose: "morning_wellness_check",
    context: {
      questions: [
        "How did you sleep?",
        "Rate your pain level (0-10)",
        "Have you taken your morning medications?",
        "Any new symptoms?"
      ]
    }
  });
}

Care Plan Follow-ups

// Schedule weekly progress checks
async function scheduleProgressChecks(patient) {
  await createSchedule({
    recipient_id: patient.id,
    agent_id: carePlanAgent.id,
    scheduled_time: getPreferredTime(patient),
    repeat_rule: "weekly",
    purpose: "care_plan_review",
    context: {
      care_plan: patient.metadata.care_plan,
      last_visit_summary: await getLastVisitSummary(patient.id),
      progress_metrics: await getProgressMetrics(patient.id)
    }
  });
}

4. EHR Integration

Integrate with your Electronic Health Record system to maintain up-to-date patient information:

// Example integration with FHIR-compliant EHR
const ehrClient = new FHIRClient({
  baseUrl: process.env.EHR_API_URL,
  auth: process.env.EHR_API_KEY
});

// Sync patient data
async function syncPatientData() {
  const patients = await ehrClient.Patient.search({
    _lastUpdated: 'gt' + lastSyncTime
  });

  for (const patient of patients) {
    // Update recipient data
    await updateRecipient(patient.id, {
      metadata: {
        conditions: await getConditions(patient.id),
        medications: await getMedications(patient.id),
        appointments: await getAppointments(patient.id)
      }
    });

    // Update agent context
    await updateContext(patient.id, {
      medical_history: await getMedicalHistory(patient.id),
      recent_visits: await getRecentVisits(patient.id)
    });
  }
}

Common Use Cases

Nursing Homes

  • Regular wellness checks throughout the day
  • Medication adherence monitoring
  • Activity reminders and encouragement
  • Family communication updates
  • Staff notification for urgent needs

Telehealth Platforms

  • Pre-appointment symptom collection
  • Post-visit care plan follow-up
  • Prescription refill reminders
  • Remote monitoring check-ins
  • Appointment scheduling assistance

Small Clinics

  • Appointment reminders and confirmations
  • Lab result notifications
  • Treatment adherence monitoring
  • Patient satisfaction follow-ups
  • Preventive care reminders

Best Practices

  • Maintain clear documentation of all automated communications
  • Set up emergency escalation protocols
  • Regularly update care plans and agent knowledge
  • Monitor interaction success rates
  • Respect patient communication preferences
  • Implement proper error handling
  • Regular testing of emergency protocols

Testing

Use our HIPAA-compliant testing environment:

# Set up test environment
export SPARKCO_API_KEY=sk_test_...
export EHR_API_KEY=ehr_test_...

# Run compliance tests
npm run test:hipaa-compliance

# Test emergency protocols
npm run test:emergency-scenarios

# Verify data security
npm run test:encryption-validation