Medical Records APIs

This document covers all medical records-related endpoints for managing prescriptions, medical documents, patient history, and health records.

Authentication

All medical records endpoints require authentication. Include the JWT token in the Authorization header:

Authorization: Bearer YOUR_AUTH_TOKEN

Base URLs

Prescriptions: /prescriptions
Medical Documents: /medical_documents
Care Plans: /care_plans
Medical History: /medical_history
Vitals: /vitals

Endpoints Overview

Prescriptions

Method	Endpoint	Description
GET	`/prescriptions`	List prescriptions
POST	`/prescriptions`	Create prescription
GET	`/prescriptions/:id`	Get prescription details
PUT	`/prescriptions/:id`	Update prescription
DELETE	`/prescriptions/:id`	Delete prescription
POST	`/prescriptions/:id/print`	Generate prescription PDF
POST	`/prescriptions/:id/send`	Send prescription to patient

Medical Documents

Method	Endpoint	Description
GET	`/medical_documents`	List documents
POST	`/medical_documents`	Upload document
GET	`/medical_documents/:id`	Get document details
PUT	`/medical_documents/:id`	Update document
DELETE	`/medical_documents/:id`	Delete document
GET	`/medical_documents/:id/download`	Download document

Care Plans

Method	Endpoint	Description
GET	`/care_plans`	List care plans
POST	`/care_plans`	Create care plan
GET	`/care_plans/:id`	Get care plan details
PUT	`/care_plans/:id`	Update care plan
DELETE	`/care_plans/:id`	Delete care plan

Medical History

Method	Endpoint	Description
GET	`/patients/:id/medical_history`	Get patient medical history
POST	`/patients/:id/medical_history`	Add medical history entry
PUT	`/medical_history/:id`	Update history entry

Vitals

Method	Endpoint	Description
GET	`/patients/:id/vitals`	Get patient vitals
POST	`/patients/:id/vitals`	Record vitals
GET	`/vitals/:id`	Get specific vital record

Prescriptions

GET /prescriptions

List prescriptions with filtering options.

Query Parameters

Parameter	Type	Description
`patient_id`	Integer	Filter by patient
`doctor_id`	Integer	Filter by doctor
`appointment_id`	Integer	Filter by appointment
`start_date`	String	Date range start
`end_date`	String	Date range end
`status`	String	Filter by status
`page`	Integer	Page number

Status Values

active - Currently valid prescription
completed - Treatment completed
cancelled - Cancelled by doctor
expired - Past validity period

Example Request

curl -X GET "http://localhost:3000/prescriptions?patient_id=456&status=active" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 123,
      "patient_id": 456,
      "doctor_id": 789,
      "appointment_id": 101,
      "prescription_date": "2025-01-15",
      "status": "active",
      "diagnosis": "Common cold with mild fever",
      "symptoms": ["Fever", "Cough", "Body aches"],
      "patient": {
        "id": 456,
        "first_name": "John",
        "last_name": "Doe",
        "age": 35,
        "gender": "M"
      },
      "doctor": {
        "id": 789,
        "first_name": "Dr. Sarah",
        "last_name": "Smith",
        "speciality": "General Physician",
        "registration_number": "MCI123456"
      },
      "medicines": [
        {
          "id": 1,
          "medicine_name": "Paracetamol",
          "generic_name": "Acetaminophen",
          "dosage": "500mg",
          "frequency": "Twice daily",
          "duration": "5 days",
          "quantity": 10,
          "instructions": "Take after meals",
          "morning": true,
          "afternoon": false,
          "evening": true,
          "before_food": false,
          "after_food": true
        },
        {
          "id": 2,
          "medicine_name": "Azithromycin",
          "generic_name": "Azithromycin",
          "dosage": "250mg",
          "frequency": "Once daily",
          "duration": "3 days",
          "quantity": 3,
          "instructions": "Take on empty stomach",
          "morning": true,
          "afternoon": false,
          "evening": false,
          "before_food": true,
          "after_food": false
        }
      ],
      "investigations": [
        {
          "id": 1,
          "test_name": "Complete Blood Count",
          "notes": "If fever persists after 3 days",
          "urgent": false
        }
      ],
      "advice": [
        "Rest for 2-3 days",
        "Drink plenty of fluids",
        "Avoid cold foods"
      ],
      "follow_up_date": "2025-01-22",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 5
  }
}

POST /prescriptions

Create a new prescription.

Request Body

{
  "prescription": {
    "patient_id": 456,
    "appointment_id": 101,
    "diagnosis": "Common cold with mild fever",
    "symptoms": ["Fever", "Cough", "Body aches"],
    "medicines": [
      {
        "medicine_name": "Paracetamol",
        "generic_name": "Acetaminophen",
        "dosage": "500mg",
        "frequency": "Twice daily",
        "duration": "5 days",
        "quantity": 10,
        "instructions": "Take after meals",
        "morning": true,
        "evening": true,
        "after_food": true
      }
    ],
    "investigations": [
      {
        "test_name": "Complete Blood Count",
        "notes": "If fever persists",
        "urgent": false
      }
    ],
    "advice": [
      "Rest for 2-3 days",
      "Drink plenty of fluids"
    ],
    "follow_up_date": "2025-01-22"
  }
}

Example Request

curl -X POST http://localhost:3000/prescriptions \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prescription": {
      "patient_id": 456,
      "diagnosis": "Common cold",
      "medicines": [
        {
          "medicine_name": "Paracetamol",
          "dosage": "500mg",
          "frequency": "Twice daily",
          "duration": "5 days"
        }
      ]
    }
  }'

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": 123,
    "prescription_number": "RX-2025-001",
    "patient_id": 456,
    "diagnosis": "Common cold",
    "status": "active",
    "prescription_date": "2025-01-15",
    "medicines": [...],
    "created_at": "2025-01-15T10:30:00Z"
  },
  "message": "Prescription created successfully"
}

POST /prescriptions/:id/print

Generate printable PDF for prescription.

Query Parameters

Parameter	Type	Description
`format`	String	Output format (pdf/html)
`template`	String	Template style (default/letterhead)

Example Request

curl -X POST "http://localhost:3000/prescriptions/123/print?format=pdf" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Success Response

{
  "success": true,
  "data": {
    "download_url": "/downloads/prescriptions/RX-2025-001.pdf",
    "expires_at": "2025-01-15T12:30:00Z"
  }
}

POST /prescriptions/:id/send

Send prescription to patient via SMS/WhatsApp/Email.

Request Body

{
  "send_via": ["sms", "whatsapp"],
  "include_pdf": true,
  "custom_message": "Your prescription is ready for pickup"
}

Example Request

curl -X POST http://localhost:3000/prescriptions/123/send \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "send_via": ["whatsapp"],
    "include_pdf": true
  }'

Medical Documents

GET /medical_documents

List medical documents with filtering.

Query Parameters

Parameter	Type	Description
`patient_id`	Integer	Filter by patient
`document_type`	String	Filter by document type
`start_date`	String	Date range start
`end_date`	String	Date range end
`page`	Integer	Page number

Document Types

lab_report - Laboratory test results
scan - Medical imaging (X-ray, MRI, etc.)
prescription - Prescription documents
discharge_summary - Hospital discharge summary
vaccination_record - Vaccination certificates
insurance - Insurance documents
other - Other medical documents

Example Request

curl -X GET "http://localhost:3000/medical_documents?patient_id=456&document_type=lab_report" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 789,
      "patient_id": 456,
      "document_type": "lab_report",
      "title": "Complete Blood Count Report",
      "description": "CBC test results from Apollo Lab",
      "document_date": "2025-01-14",
      "file_name": "cbc_report_20250114.pdf",
      "file_size": 245760,
      "mime_type": "application/pdf",
      "url": "/documents/789/cbc_report_20250114.pdf",
      "thumbnail_url": "/documents/789/thumbnail.jpg",
      "tags": ["blood_test", "routine_checkup"],
      "uploaded_by": {
        "id": 101,
        "name": "Dr. Sarah Smith",
        "type": "doctor"
      },
      "patient": {
        "id": 456,
        "name": "John Doe"
      },
      "created_at": "2025-01-14T16:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 12
  }
}

POST /medical_documents

Upload a new medical document.

Request (Multipart Form)

Content-Type: multipart/form-data

patient_id: 456
document_type: lab_report
title: Complete Blood Count Report
description: CBC test results
document_date: 2025-01-14
tags: blood_test,routine
file: [binary file data]

Example Request (using curl)

curl -X POST http://localhost:3000/medical_documents \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -F "patient_id=456" \
  -F "document_type=lab_report" \
  -F "title=CBC Report" \
  -F "file=@/path/to/document.pdf"

Success Response (201 Created)

{
  "success": true,
  "data": {
    "id": 789,
    "patient_id": 456,
    "document_type": "lab_report",
    "title": "Complete Blood Count Report",
    "file_name": "cbc_report_20250114.pdf",
    "url": "/documents/789/cbc_report_20250114.pdf",
    "created_at": "2025-01-14T16:45:00Z"
  },
  "message": "Document uploaded successfully"
}

Care Plans

GET /care_plans

List care plans for patients.

Query Parameters

Parameter	Type	Description
`patient_id`	Integer	Filter by patient
`status`	String	Filter by status (active/completed/cancelled)
`condition`	String	Filter by medical condition

Example Request

curl -X GET "http://localhost:3000/care_plans?patient_id=456" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 321,
      "patient_id": 456,
      "title": "Diabetes Management Plan",
      "condition": "Type 2 Diabetes",
      "status": "active",
      "start_date": "2025-01-15",
      "end_date": "2025-04-15",
      "created_by": {
        "id": 789,
        "name": "Dr. Sarah Smith"
      },
      "goals": [
        {
          "id": 1,
          "title": "Maintain HbA1c below 7%",
          "target_value": "7.0",
          "current_value": "8.2",
          "unit": "%",
          "due_date": "2025-04-15"
        },
        {
          "id": 2,
          "title": "Lose 5kg weight",
          "target_value": "70",
          "current_value": "75",
          "unit": "kg",
          "due_date": "2025-04-15"
        }
      ],
      "tasks": [
        {
          "id": 1,
          "title": "Check blood sugar daily",
          "frequency": "daily",
          "status": "active",
          "last_completed": "2025-01-14"
        },
        {
          "id": 2,
          "title": "Take Metformin",
          "frequency": "twice_daily",
          "status": "active",
          "instructions": "500mg with breakfast and dinner"
        }
      ],
      "appointments": [
        {
          "id": 101,
          "appointment_date": "2025-02-15",
          "type": "follow_up",
          "status": "scheduled"
        }
      ],
      "notes": "Patient needs regular monitoring of blood glucose levels",
      "created_at": "2025-01-15T09:00:00Z"
    }
  ]
}

POST /care_plans

Create a new care plan.

Request Body

{
  "care_plan": {
    "patient_id": 456,
    "title": "Diabetes Management Plan",
    "condition": "Type 2 Diabetes",
    "start_date": "2025-01-15",
    "end_date": "2025-04-15",
    "goals": [
      {
        "title": "Maintain HbA1c below 7%",
        "target_value": "7.0",
        "unit": "%",
        "due_date": "2025-04-15"
      }
    ],
    "tasks": [
      {
        "title": "Check blood sugar daily",
        "frequency": "daily",
        "instructions": "Check fasting and post-meal"
      }
    ],
    "notes": "Regular monitoring required"
  }
}

Medical History

GET /patients/:id/medical_history

Get patient's complete medical history.

Query Parameters

Parameter	Type	Description
`category`	String	Filter by category (allergies/medications/surgeries)
`start_date`	String	Date range start
`end_date`	String	Date range end

Example Request

curl -X GET http://localhost:3000/patients/456/medical_history \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Example Response

{
  "success": true,
  "data": {
    "patient_id": 456,
    "patient": {
      "id": 456,
      "name": "John Doe",
      "age": 35,
      "gender": "M"
    },
    "allergies": [
      {
        "id": 1,
        "allergen": "Penicillin",
        "reaction": "Skin rash",
        "severity": "moderate",
        "notes": "Developed rash after taking antibiotic",
        "recorded_date": "2024-06-15"
      }
    ],
    "chronic_conditions": [
      {
        "id": 1,
        "condition": "Type 2 Diabetes",
        "diagnosed_date": "2023-03-20",
        "status": "active",
        "notes": "Well controlled with Metformin"
      }
    ],
    "medications": [
      {
        "id": 1,
        "medicine_name": "Metformin",
        "dosage": "500mg",
        "frequency": "Twice daily",
        "start_date": "2023-03-20",
        "status": "active",
        "prescribed_by": "Dr. Sarah Smith"
      }
    ],
    "surgeries": [
      {
        "id": 1,
        "procedure": "Appendectomy",
        "date": "2020-08-15",
        "hospital": "City General Hospital",
        "surgeon": "Dr. Michael Johnson",
        "notes": "Laparoscopic procedure, no complications"
      }
    ],
    "family_history": [
      {
        "id": 1,
        "relation": "Father",
        "condition": "Hypertension",
        "age_of_onset": 45
      }
    ],
    "social_history": {
      "smoking": "never",
      "alcohol": "occasional",
      "exercise": "regular",
      "diet": "balanced"
    }
  }
}

POST /patients/:id/medical_history

Add new medical history entry.

Request Body

{
  "medical_history": {
    "category": "allergy",
    "allergen": "Peanuts",
    "reaction": "Anaphylaxis",
    "severity": "severe",
    "notes": "Immediate reaction after eating peanuts"
  }
}

Vitals

GET /patients/:id/vitals

Get patient's vital signs history.

Query Parameters

Parameter	Type	Description
`start_date`	String	Date range start
`end_date`	String	Date range end
`vital_type`	String	Filter by vital type
`limit`	Integer	Number of records to return

Vital Types

all - All vital signs
blood_pressure - Blood pressure readings
weight - Weight measurements
temperature - Temperature readings
pulse - Pulse rate
blood_sugar - Blood glucose levels

Example Request

curl -X GET "http://localhost:3000/patients/456/vitals?limit=10" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 567,
      "patient_id": 456,
      "recorded_date": "2025-01-15",
      "recorded_by": {
        "id": 789,
        "name": "Nurse Mary",
        "type": "staff"
      },
      "vitals": {
        "weight": 75.5,
        "height": 175,
        "bmi": 24.6,
        "temperature": 98.6,
        "bp_systolic": 120,
        "bp_diastolic": 80,
        "pulse": 72,
        "respiratory_rate": 16,
        "oxygen_saturation": 98,
        "blood_sugar_fasting": 110,
        "blood_sugar_pp": 140
      },
      "notes": "Patient feeling well",
      "appointment_id": 101,
      "created_at": "2025-01-15T09:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "total": 25
  }
}

POST /patients/:id/vitals

Record new vital signs.

Request Body

{
  "vitals": {
    "weight": 75.5,
    "height": 175,
    "temperature": 98.6,
    "bp_systolic": 120,
    "bp_diastolic": 80,
    "pulse": 72,
    "respiratory_rate": 16,
    "oxygen_saturation": 98,
    "blood_sugar_fasting": 110,
    "notes": "Patient feeling well"
  }
}

Example Request

curl -X POST http://localhost:3000/patients/456/vitals \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vitals": {
      "weight": 75.5,
      "bp_systolic": 120,
      "bp_diastolic": 80,
      "pulse": 72
    }
  }'

Document Templates

GET /document_templates

Get available prescription and document templates.

Example Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Standard Prescription",
      "type": "prescription",
      "description": "Standard prescription template with clinic letterhead",
      "fields": ["doctor_info", "patient_info", "medicines", "advice"]
    },
    {
      "id": 2,
      "name": "Discharge Summary",
      "type": "discharge_summary",
      "description": "Hospital discharge summary template",
      "fields": ["admission_details", "diagnosis", "treatment", "discharge_instructions"]
    }
  ]
}

Medical Coding

GET /icd_codes/search

Search ICD-10 diagnosis codes.

Query Parameters

Parameter	Type	Description
`query`	String	Search term
`limit`	Integer	Number of results

Example Request

curl -X GET "http://localhost:3000/icd_codes/search?query=diabetes&limit=10" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "code": "E11",
      "description": "Type 2 diabetes mellitus",
      "category": "Endocrine, nutritional and metabolic diseases"
    },
    {
      "code": "E11.9",
      "description": "Type 2 diabetes mellitus without complications",
      "category": "Endocrine, nutritional and metabolic diseases"
    }
  ]
}

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - No permission to access records
404	Not Found - Record doesn't exist
413	Payload Too Large - File size too large
415	Unsupported Media Type - Invalid file type
422	Unprocessable Entity - Validation errors

File Upload Limits

File Type	Max Size	Allowed Formats
Images	5MB	JPG, PNG, GIF
Documents	10MB	PDF, DOC, DOCX
Lab Reports	20MB	PDF, JPG, PNG

Common Error Messages

{
  "success": false,
  "error": "File too large",
  "details": "Maximum file size allowed is 10MB"
}

{
  "success": false,
  "error": "Invalid file type",
  "details": "Only PDF, JPG, PNG files are allowed"
}

Patient APIs - Patient information and management
Appointment APIs - Appointment-based medical records
Doctor APIs - Doctor profiles and specializations

Medical Records APIs

AuthenticationCopy Anchor Link

Base URLsCopy Anchor Link

Endpoints OverviewCopy Anchor Link

PrescriptionsCopy Anchor Link

Medical DocumentsCopy Anchor Link

Care PlansCopy Anchor Link

Medical HistoryCopy Anchor Link

VitalsCopy Anchor Link

PrescriptionsCopy Anchor Link

GET /prescriptionsCopy Anchor Link

Query ParametersCopy Anchor Link

Status ValuesCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

POST /prescriptionsCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

Success Response (201 Created)Copy Anchor Link

POST /prescriptions/:id/printCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Success ResponseCopy Anchor Link

POST /prescriptions/:id/sendCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

Medical DocumentsCopy Anchor Link

GET /medical_documentsCopy Anchor Link

Query ParametersCopy Anchor Link

Document TypesCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

POST /medical_documentsCopy Anchor Link

Request (Multipart Form)Copy Anchor Link

Example Request (using curl)Copy Anchor Link

Success Response (201 Created)Copy Anchor Link

Care PlansCopy Anchor Link

GET /care_plansCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

POST /care_plansCopy Anchor Link

Request BodyCopy Anchor Link

Medical HistoryCopy Anchor Link

GET /patients/:id/medical_historyCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

POST /patients/:id/medical_historyCopy Anchor Link

Request BodyCopy Anchor Link

VitalsCopy Anchor Link

GET /patients/:id/vitalsCopy Anchor Link

Query ParametersCopy Anchor Link

Vital TypesCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

POST /patients/:id/vitalsCopy Anchor Link

Request BodyCopy Anchor Link

Example RequestCopy Anchor Link

Document TemplatesCopy Anchor Link

GET /document_templatesCopy Anchor Link

Example ResponseCopy Anchor Link

Medical CodingCopy Anchor Link

GET /icd_codes/searchCopy Anchor Link

Query ParametersCopy Anchor Link

Example RequestCopy Anchor Link

Example ResponseCopy Anchor Link

Error CodesCopy Anchor Link

File Upload LimitsCopy Anchor Link

Common Error MessagesCopy Anchor Link

Related EndpointsCopy Anchor Link

On this page

Authentication

Base URLs

Endpoints Overview

Prescriptions

Medical Documents

Care Plans

Medical History

Vitals

Prescriptions

GET /prescriptions

Query Parameters

Status Values

Example Request

Example Response

POST /prescriptions

Request Body

Example Request

Success Response (201 Created)

POST /prescriptions/:id/print

Query Parameters

Example Request

Success Response

POST /prescriptions/:id/send

Request Body

Example Request

Medical Documents

GET /medical_documents

Query Parameters

Document Types

Example Request

Example Response

POST /medical_documents

Request (Multipart Form)

Example Request (using curl)

Success Response (201 Created)

Care Plans

GET /care_plans

Query Parameters

Example Request

Example Response

POST /care_plans

Request Body

Medical History

GET /patients/:id/medical_history

Query Parameters

Example Request

Example Response

POST /patients/:id/medical_history

Request Body

Vitals

GET /patients/:id/vitals

Query Parameters

Vital Types

Example Request

Example Response

POST /patients/:id/vitals

Request Body

Example Request

Document Templates

GET /document_templates

Example Response

Medical Coding

GET /icd_codes/search

Query Parameters

Example Request

Example Response

Error Codes

File Upload Limits

Common Error Messages

Related Endpoints