Skip to main content

API Documentation

MedFeed provides a comprehensive RESTful API built with Express.js and Node.js, enabling seamless integration with existing hospital systems, EMR/EHR platforms, and third-party applications.

API Overview​

Base URL​

Production: https://api.yourhospital.medfeed.io
Staging: https://staging-api.yourhospital.medfeed.io

Authentication​

All API requests require JWT authentication with proper role-based permissions.

// Authentication header
Authorization: Bearer <your-jwt-token>
Content-Type: application/json

Rate Limiting​

  • Standard Users: 1000 requests per hour
  • Premium Users: 5000 requests per hour
  • Enterprise: Custom limits based on agreement

Authentication API​

Login​

POST /api/auth/login

Request Body:

{
  "email": "doctor@hospital.com",
  "password": "securePassword123"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user123",
      "name": "Dr. John Smith",
      "email": "doctor@hospital.com",
      "role": "physician",
      "department": "cardiology"
    }
  }
}

Refresh Token​

POST /api/auth/refresh

Logout​

POST /api/auth/logout

Patient Management API​

Get Patients​

GET /api/patients

Query Parameters:

  • page (number): Page number for pagination
  • limit (number): Number of patients per page
  • department (string): Filter by department
  • status (string): Filter by patient status

Response:

{
  "success": true,
  "data": {
    "patients": [
      {
        "id": "patient123",
        "name": "John Doe",
        "mrn": "MRN001234",
        "department": "cardiology",
        "admission_date": "2024-01-15T10:30:00Z",
        "status": "active"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 10,
      "total_count": 95
    }
  }
}

Create Patient​

POST /api/patients

Request Body:

{
  "name": "Jane Smith",
  "mrn": "MRN001235",
  "date_of_birth": "1985-03-20",
  "gender": "female",
  "department": "emergency",
  "admission_reason": "Chest pain evaluation"
}

Get Patient Details​

GET /api/patients/{patient_id}

Update Patient​

PUT /api/patients/{patient_id}

Patient Timeline​

GET /api/patients/{patient_id}/timeline

Feedback Management API​

Submit Voice Feedback​

POST /api/feedback

Request Body (multipart/form-data):

const formData = new FormData();
formData.append('patient_id', 'patient123');
formData.append('feedback_type', 'discharge');
formData.append('audio_file', audioBlob, 'feedback.mp3');
formData.append('department', 'cardiology');
formData.append('priority', 'medium');

Response:

{
  "success": true,
  "data": {
    "feedback_id": "feedback456",
    "transcription_status": "processing",
    "estimated_completion": "2024-01-15T11:00:00Z"
  }
}

Get Feedback List​

GET /api/feedback

Query Parameters:

  • patient_id (string): Filter by patient
  • department (string): Filter by department
  • date_from (string): Start date (ISO 8601)
  • date_to (string): End date (ISO 8601)
  • status (string): Filter by processing status

Get Feedback Details​

GET /api/feedback/{feedback_id}

Response:

{
  "success": true,
  "data": {
    "id": "feedback456",
    "patient_id": "patient123",
    "transcription": "The patient expressed satisfaction with the nursing care...",
    "sentiment_score": 0.85,
    "satisfaction_rating": 8,
    "key_topics": ["nursing care", "communication", "pain management"],
    "alerts": [],
    "created_at": "2024-01-15T10:45:00Z",
    "processed_at": "2024-01-15T10:47:00Z"
  }
}

Update Feedback​

PUT /api/feedback/{feedback_id}

Clinical Notes API​

Create Clinical Note​

POST /api/notes

Request Body:

{
  "patient_id": "patient123",
  "note_type": "progress_note",
  "content": "Patient continues to improve. Vital signs stable...",
  "provider_id": "provider789",
  "department": "cardiology"
}

Voice-to-Note Creation​

POST /api/notes/voice

Request Body (multipart/form-data):

const formData = new FormData();
formData.append('patient_id', 'patient123');
formData.append('note_type', 'progress_note');
formData.append('audio_file', audioBlob, 'note.mp3');
formData.append('provider_id', 'provider789');

Get Notes​

GET /api/notes

Get Note Details​

GET /api/notes/{note_id}

Update Note​

PUT /api/notes/{note_id}

Share Note​

POST /api/notes/{note_id}/share

Task Management API​

Create Task​

POST /api/tasks

Request Body:

{
  "title": "Check equipment in Room 302",
  "description": "Patient reports air conditioning not working properly",
  "priority": "medium",
  "department": "maintenance",
  "assignee_id": "staff456",
  "due_date": "2024-01-15T16:00:00Z",
  "location": "Room 302"
}

Voice Task Creation​

POST /api/tasks/voice

Get Tasks​

GET /api/tasks

Query Parameters:

  • assignee_id (string): Filter by assignee
  • department (string): Filter by department
  • status (string): Filter by task status
  • priority (string): Filter by priority level

Update Task Status​

PUT /api/tasks/{task_id}/status

Request Body:

{
  "status": "in_progress",
  "progress_percentage": 50,
  "notes": "Started working on the issue, ordered replacement parts"
}

Complete Task​

POST /api/tasks/{task_id}/complete

Analytics API​

Get Dashboard KPIs​

GET /api/analytics/kpis

Response:

{
  "success": true,
  "data": {
    "patient_satisfaction": {
      "nps_score": 72,
      "csat_score": 4.2,
      "response_rate": 68
    },
    "task_metrics": {
      "completion_rate": 94,
      "average_resolution_time": 4.5,
      "overdue_tasks": 12
    },
    "clinical_metrics": {
      "notes_created": 156,
      "transcription_accuracy": 97.8,
      "documentation_time_saved": 2.3
    }
  }
}

Generate Report​

POST /api/analytics/reports

Request Body:

{
  "report_type": "patient_satisfaction",
  "date_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "filters": {
    "department": "cardiology",
    "include_charts": true
  },
  "format": "pdf"
}

Get Analytics Data​

GET /api/analytics/data

Department Management API​

Get Departments​

GET /api/departments

Create Department​

POST /api/departments

Update Department​

PUT /api/departments/{department_id}

Get Department Staff​

GET /api/departments/{department_id}/staff

User Management API​

Get Users​

GET /api/users

Create User​

POST /api/users

Update User​

PUT /api/users/{user_id}

Invite User​

POST /api/users/invite

Request Body:

{
  "email": "newdoctor@hospital.com",
  "role": "physician",
  "department": "emergency",
  "permissions": ["read_patients", "create_notes", "manage_tasks"]
}

Integration APIs​

EMR/EHR Integration​

POST /api/integrations/emr/sync

Export Data​

GET /api/export/{data_type}

Query Parameters:

  • format (string): Export format (json, csv, xml, hl7)
  • date_range (string): Date range for export
  • filters (object): Additional filters

Webhook Configuration​

POST /api/webhooks

Request Body:

{
  "url": "https://your-system.com/webhook",
  "events": ["feedback_created", "task_completed", "note_signed"],
  "secret": "webhook_secret_key"
}

Error Handling​

Standard Error Response​

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}

HTTP Status Codes​

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Internal Server Error

SDK and Libraries​

JavaScript/Node.js SDK​

npm install @medfeed/api-client
import MedFeedAPI from '@medfeed/api-client';

const client = new MedFeedAPI({
  baseURL: 'https://api.yourhospital.medfeed.io',
  token: 'your-jwt-token'
});

// Create patient
const patient = await client.patients.create({
  name: 'John Doe',
  mrn: 'MRN001234'
});

// Submit feedback
const feedback = await client.feedback.create({
  patient_id: patient.id,
  audio_file: audioBlob
});

Python SDK​

pip install medfeed-api
from medfeed_api import MedFeedClient

client = MedFeedClient(
    base_url='https://api.yourhospital.medfeed.io',
    token='your-jwt-token'
)

# Create patient
patient = client.patients.create({
    'name': 'John Doe',
    'mrn': 'MRN001234'
})

# Get feedback
feedback_list = client.feedback.list(patient_id=patient['id'])

Webhooks​

Event Types​

  • patient.created - New patient registered
  • patient.updated - Patient information updated
  • feedback.created - New feedback submitted
  • feedback.processed - Feedback transcription completed
  • note.created - New clinical note created
  • note.signed - Clinical note digitally signed
  • task.created - New task created
  • task.completed - Task marked as completed
  • alert.triggered - System alert generated

Webhook Payload Example​

{
  "event": "feedback.processed",
  "timestamp": "2024-01-15T10:47:00Z",
  "data": {
    "feedback_id": "feedback456",
    "patient_id": "patient123",
    "transcription": "Patient feedback content...",
    "sentiment_score": 0.85,
    "alerts": []
  }
}

Rate Limiting​

Headers​

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

Rate Limit Response​

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "retry_after": 60
  }
}

Testing​

Postman Collection​

Download our comprehensive Postman collection for API testing:

https://api.medfeed.io/postman/collection.json

Test Environment​

Base URL: https://test-api.medfeed.io
Test Token: test_token_12345

Sample Data​

Use our test data endpoints for development:

GET /api/test/sample-patients
GET /api/test/sample-feedback
GET /api/test/sample-tasks

Need help with API integration? Contact our developer support team or check our Integration Guide for detailed examples.