Patient APIs

APIs for managing patient records, medical history, and patient-related information within clinic context.

Overview

Patient APIs handle patient registration, profile management, medical history, and clinic-specific patient records.

Base Path: /patients (global) or /clinic_patients (clinic-specific)

Authentication: Required for all endpoints

Profile Context: Clinic staff or patient profile access required

Endpoints

Patient Profile Management

Get Patient Profile

Retrieves patient profile information.

GET /patients/:id

Success Response:

{
  "success": true,
  "data": {
    "id": 201,
    "user_id": 789,
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "phone_number": "9876543210",
    "email": "john.doe@email.com",
    "date_of_birth": "1990-05-15",
    "age": 34,
    "gender": "M",
    "blood_group": "O+",
    "address": "123 Main Street, Apartment 4B",
    "city": "Mumbai",
    "state": "Maharashtra",
    "pincode": "400001",
    "emergency_contact": {
      "name": "Jane Doe",
      "relation": "Spouse",
      "phone_number": "9876543211"
    },
    "medical_info": {
      "allergies": ["Penicillin", "Peanuts"],
      "chronic_conditions": ["Hypertension", "Diabetes Type 2"],
      "blood_group": "O+",
      "height": 175,
      "weight": 70,
      "bmi": 22.9
    },
    "insurance": {
      "provider": "Star Health",
      "policy_number": "SH12345678",
      "expiry_date": "2024-12-31",
      "coverage_amount": 500000
    },
    "preferences": {
      "preferred_language": "English",
      "communication_method": "SMS",
      "appointment_reminders": true
    },
    "stats": {
      "total_appointments": 45,
      "last_visit": "2024-01-18T14:30:00Z",
      "total_clinics": 3,
      "member_since": "2022-03-15"
    },
    "created_at": "2022-03-15T09:00:00Z",
    "updated_at": "2024-01-20T11:15:00Z"
  }
}

Update Patient Profile

Updates patient profile information.

PUT /patients/:id

Request Body:

{
  "patient": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "updated.email@domain.com",
    "address": "New Address, City",
    "weight": 72,
    "emergency_contact": {
      "name": "Jane Doe",
      "phone_number": "9876543211",
      "relation": "Wife"
    },
    "preferences": {
      "preferred_language": "Hindi",
      "appointment_reminders": false
    }
  }
}

Get Current Patient Profile

Gets the profile of the currently authenticated patient.

GET /patients/me

Clinic-Specific Patient Records

List Clinic Patients

Gets all patients registered with the current clinic.

GET /clinic_patients

Query Parameters:

Parameter	Type	Description
search	string	Search by name, phone, or ID
age_min	integer	Minimum age
age_max	integer	Maximum age
gender	string	Filter by gender: M, F, O
last_visit_after	date	Patients visited after date
has_upcoming_appointments	boolean	Has future appointments
page	integer	Page number
per_page	integer	Items per page
sort	string	Sort by: name, last_visit, created_at

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 1001,
      "patient_id": 201,
      "patient_code": "P001234",
      "name": "John Doe",
      "phone_number": "9876543210",
      "age": 34,
      "gender": "M",
      "last_visit": "2024-01-18T14:30:00Z",
      "total_visits": 8,
      "upcoming_appointments": 1,
      "registration_date": "2022-03-15",
      "tags": ["Regular Patient", "Diabetic"],
      "status": "active"
    },
    {
      "id": 1002,
      "patient_id": 202,
      "patient_code": "P001235", 
      "name": "Jane Smith",
      "phone_number": "9876543212",
      "age": 28,
      "gender": "F",
      "last_visit": "2024-01-15T10:00:00Z",
      "total_visits": 3,
      "upcoming_appointments": 0,
      "registration_date": "2023-11-20",
      "tags": ["New Patient"],
      "status": "active"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 25,
      "total_count": 620,
      "per_page": 25
    },
    "stats": {
      "total_patients": 620,
      "active_patients": 580,
      "new_patients_this_month": 15,
      "average_age": 35.2
    }
  }
}

Get Clinic Patient Details

Gets detailed information for a patient within clinic context.

GET /clinic_patients/:id

Success Response:

{
  "success": true,
  "data": {
    "id": 1001,
    "patient_id": 201,
    "clinic_id": 123,
    "patient_code": "P001234",
    "registration_date": "2022-03-15",
    "patient_info": {
      "name": "John Doe",
      "age": 34,
      "gender": "M",
      "phone_number": "9876543210",
      "email": "john.doe@email.com",
      "address": "123 Main Street",
      "blood_group": "O+",
      "allergies": ["Penicillin"]
    },
    "clinic_specific": {
      "notes": "Regular patient, well-controlled diabetes",
      "tags": ["Regular Patient", "Diabetic", "Compliant"],
      "preferred_doctor": {
        "id": 101,
        "name": "Dr. Sarah Johnson"
      },
      "referred_by": "Dr. Smith from City Hospital",
      "source": "Walk-in"
    },
    "visit_history": {
      "total_visits": 8,
      "last_visit": "2024-01-18T14:30:00Z",
      "first_visit": "2022-03-15T11:00:00Z",
      "average_visits_per_month": 1.2,
      "no_shows": 1,
      "cancelled_appointments": 2
    },
    "medical_summary": {
      "chronic_conditions": ["Hypertension", "Diabetes Type 2"],
      "current_medications": [
        "Metformin 500mg - Twice daily",
        "Lisinopril 10mg - Once daily"
      ],
      "recent_vitals": {
        "date": "2024-01-18",
        "bp": "130/85",
        "weight": 70,
        "temperature": 98.6,
        "pulse": 72
      }
    },
    "recent_appointments": [
      {
        "id": 5001,
        "date": "2024-01-18",
        "doctor": "Dr. Sarah Johnson",
        "type": "Follow-up",
        "status": "completed",
        "diagnosis": "Diabetes follow-up - well controlled"
      }
    ],
    "billing_info": {
      "outstanding_amount": 0,
      "total_paid": 12500,
      "last_payment": "2024-01-18",
      "payment_method": "Cash"
    }
  }
}

Register New Patient

Registers a new patient with the clinic.

POST /clinic_patients

Request Body:

{
  "clinic_patient": {
    "first_name": "Alice",
    "last_name": "Johnson", 
    "phone_number": "9876543213",
    "country_code": "91",
    "email": "alice.johnson@email.com",
    "date_of_birth": "1985-08-20",
    "gender": "F",
    "blood_group": "A+",
    "address": "456 Oak Street",
    "city": "Mumbai",
    "pincode": "400002",
    "emergency_contact": {
      "name": "Bob Johnson",
      "relation": "Husband",
      "phone_number": "9876543214"
    },
    "allergies": ["Dust", "Pollen"],
    "referred_by": "Dr. Williams",
    "source": "Online booking",
    "notes": "New patient with seasonal allergies"
  }
}

Success Response:

{
  "success": true,
  "data": {
    "id": 1003,
    "patient_code": "P001236",
    "name": "Alice Johnson",
    "phone_number": "9876543213",
    "registration_date": "2024-01-21",
    "status": "active"
  },
  "message": "Patient registered successfully"
}

Update Clinic Patient

Updates clinic-specific patient information.

PUT /clinic_patients/:id

Request Body:

{
  "clinic_patient": {
    "notes": "Updated patient notes",
    "tags": ["Regular Patient", "Allergies"],
    "preferred_doctor_id": 102,
    "status": "active"
  }
}

Patient Medical History

Get Patient Medical History

Retrieves comprehensive medical history for a patient.

GET /patients/:id/medical_history

Success Response:

{
  "success": true,
  "data": {
    "patient_id": 201,
    "basic_info": {
      "blood_group": "O+",
      "height": 175,
      "weight": 70,
      "bmi": 22.9,
      "allergies": ["Penicillin", "Peanuts"],
      "smoking": "Never",
      "alcohol": "Occasional",
      "exercise": "Regular"
    },
    "chronic_conditions": [
      {
        "condition": "Type 2 Diabetes",
        "diagnosed_date": "2020-03-15",
        "severity": "Moderate",
        "controlled": true,
        "medications": ["Metformin 500mg BD"]
      },
      {
        "condition": "Hypertension",
        "diagnosed_date": "2019-08-10",
        "severity": "Mild",
        "controlled": true,
        "medications": ["Lisinopril 10mg OD"]
      }
    ],
    "family_history": {
      "father": {
        "conditions": ["Diabetes", "Heart Disease"],
        "age_at_diagnosis": {"Diabetes": 55, "Heart Disease": 62}
      },
      "mother": {
        "conditions": ["Hypertension"],
        "age_at_diagnosis": {"Hypertension": 58}
      },
      "siblings": []
    },
    "surgical_history": [
      {
        "surgery": "Appendectomy",
        "date": "2015-06-20",
        "hospital": "City General Hospital",
        "complications": "None"
      }
    ],
    "immunizations": [
      {
        "vaccine": "COVID-19 Vaccine",
        "date": "2021-05-15",
        "dose": "2nd Dose",
        "manufacturer": "Covishield"
      },
      {
        "vaccine": "Hepatitis B",
        "date": "2018-03-10",
        "dose": "Complete Series"
      }
    ],
    "vital_trends": {
      "weight": [
        {"date": "2024-01-18", "value": 70},
        {"date": "2023-10-15", "value": 72},
        {"date": "2023-07-10", "value": 71}
      ],
      "bp_systolic": [
        {"date": "2024-01-18", "value": 130},
        {"date": "2023-10-15", "value": 135},
        {"date": "2023-07-10", "value": 140}
      ]
    }
  }
}

Update Medical History

Updates patient's medical history information.

PUT /patients/:id/medical_history

Request Body:

{
  "medical_history": {
    "weight": 68,
    "allergies": ["Penicillin", "Shellfish"],
    "smoking": "Former smoker",
    "chronic_conditions": [
      {
        "condition": "Type 2 Diabetes",
        "controlled": true,
        "medications": ["Metformin 500mg BD", "Glimepiride 2mg OD"]
      }
    ]
  }
}

Patient Appointments History

Get Patient Appointments

Retrieves appointment history for a patient.

GET /patients/:id/appointments

Query Parameters:

Parameter	Type	Description
clinic_id	integer	Filter by specific clinic
status	string	Filter by status
start_date	date	Appointments after date
end_date	date	Appointments before date
page	integer	Page number

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 5001,
      "appointment_date": "2024-01-18",
      "appointment_time": "14:30",
      "doctor": {
        "id": 101,
        "name": "Dr. Sarah Johnson",
        "speciality": "Internal Medicine"
      },
      "clinic": {
        "id": 123,
        "name": "City Health Clinic"
      },
      "type": "Follow-up",
      "status": "completed",
      "chief_complaint": "Diabetes follow-up",
      "diagnosis": "Type 2 Diabetes - well controlled",
      "consultation_fee": 600,
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": 5000,
      "appointment_date": "2023-10-15",
      "appointment_time": "11:00",
      "doctor": {
        "id": 101,
        "name": "Dr. Sarah Johnson",
        "speciality": "Internal Medicine"
      },
      "clinic": {
        "id": 123,
        "name": "City Health Clinic"
      },
      "type": "Consultation",
      "status": "completed", 
      "chief_complaint": "High blood pressure",
      "diagnosis": "Hypertension",
      "consultation_fee": 800,
      "created_at": "2023-10-12T09:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_count": 45,
      "per_page": 10
    },
    "stats": {
      "total_appointments": 45,
      "completed": 40,
      "cancelled": 3,
      "no_shows": 2
    }
  }
}

Patient Search & Discovery

Search Patients

Search for patients across the system (admin only).

GET /patients/search

Query Parameters:

Parameter	Type	Description
q	string	Search query (name, phone)
phone_number	string	Exact phone number search
age_min	integer	Minimum age
age_max	integer	Maximum age
city	string	Filter by city
has_conditions	string	Has specific medical condition
registered_after	date	Registered after date

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 201,
      "name": "John Doe",
      "phone_number": "987***3210",
      "age": 34,
      "city": "Mumbai",
      "total_clinics": 3,
      "last_visit": "2024-01-18",
      "chronic_conditions": ["Diabetes", "Hypertension"]
    }
  ]
}

Patient Documents & Files

List Patient Documents

Gets all documents uploaded for a patient.

GET /patients/:id/documents

Query Parameters:

Parameter	Type	Description
type	string	Filter by document type
clinic_id	integer	Filter by clinic
uploaded_after	date	Documents after date

Success Response:

{
  "success": true,
  "data": [
    {
      "id": 801,
      "filename": "lab_report_cbc.pdf",
      "type": "lab_report",
      "size": 245760,
      "upload_date": "2024-01-18",
      "uploaded_by": "Dr. Sarah Johnson",
      "clinic": "City Health Clinic",
      "appointment_id": 5001,
      "url": "https://s3.amazonaws.com/...",
      "description": "Complete Blood Count report"
    },
    {
      "id": 802,
      "filename": "prescription_20240115.pdf", 
      "type": "prescription",
      "size": 156432,
      "upload_date": "2024-01-15",
      "uploaded_by": "Dr. Sarah Johnson",
      "clinic": "City Health Clinic",
      "appointment_id": 5000,
      "url": "https://s3.amazonaws.com/...",
      "description": "Prescription for diabetes medication"
    }
  ]
}

Upload Patient Document

Uploads a new document for the patient.

POST /patients/:id/documents

Request (multipart/form-data):

file: [binary file data]
type: lab_report
description: Blood test results
clinic_id: 123
appointment_id: 5001

Success Response:

{
  "success": true,
  "data": {
    "id": 803,
    "filename": "blood_test_results.pdf",
    "type": "lab_report",
    "size": 189456,
    "url": "https://s3.amazonaws.com/...",
    "upload_date": "2024-01-21"
  },
  "message": "Document uploaded successfully"
}

Patient Analytics

Get Patient Statistics

Gets statistics for clinic's patient base.

GET /clinic_patients/analytics

Query Parameters:

Parameter	Type	Description
period	string	Time period: month, quarter, year
start_date	date	Custom start date
end_date	date	Custom end date

Success Response:

{
  "success": true,
  "data": {
    "overview": {
      "total_patients": 620,
      "active_patients": 580,
      "new_registrations_this_month": 15,
      "returning_patients_this_month": 89
    },
    "demographics": {
      "age_distribution": {
        "0-18": 124,
        "19-35": 186,
        "36-50": 158,
        "51-65": 98,
        "65+": 54
      },
      "gender_distribution": {
        "male": 312,
        "female": 295,
        "other": 13
      }
    },
    "geographic": {
      "top_cities": [
        {"city": "Mumbai", "count": 245},
        {"city": "Pune", "count": 89},
        {"city": "Nagpur", "count": 67}
      ]
    },
    "medical_conditions": {
      "most_common": [
        {"condition": "Hypertension", "count": 89},
        {"condition": "Diabetes", "count": 67},
        {"condition": "Asthma", "count": 45}
      ]
    },
    "engagement": {
      "average_visits_per_patient": 3.2,
      "patient_retention_rate": 78.5,
      "no_show_rate": 12.3
    }
  }
}

Error Responses

Common Error Codes

Code	Status	Description
PATIENT_NOT_FOUND	404	Patient not found
UNAUTHORIZED_PATIENT_ACCESS	403	No access to patient record
PATIENT_ALREADY_REGISTERED	422	Patient already registered in clinic
INVALID_PATIENT_DATA	422	Patient data validation failed
DOCUMENT_UPLOAD_FAILED	422	Document upload failed
MEDICAL_HISTORY_INCOMPLETE	422	Required medical history missing

Example Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_PATIENT_DATA",
    "message": "Patient validation failed",
    "details": {
      "phone_number": ["has invalid format"],
      "date_of_birth": ["cannot be in the future"],
      "email": ["has invalid format"]
    }
  }
}

Webhooks

Patient-related webhooks:

patient.registered - New patient registered
patient.updated - Patient profile updated
patient.medical_history_updated - Medical history modified
patient.document_uploaded - New document uploaded
patient.appointment_completed - Appointment completed

Examples

Complete Patient Registration Flow

# 1. Register new patient
curl -X POST https://api.kulcare.com/clinic_patients \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clinic_patient": {
      "first_name": "Alice",
      "last_name": "Smith",
      "phone_number": "9876543215",
      "date_of_birth": "1985-08-20",
      "gender": "F",
      "blood_group": "A+"
    }
  }'

# 2. Update medical history
curl -X PUT https://api.kulcare.com/patients/201/medical_history \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "medical_history": {
      "allergies": ["Dust", "Pollen"],
      "chronic_conditions": [
        {"condition": "Asthma", "controlled": true}
      ]
    }
  }'

# 3. Upload document
curl -X POST https://api.kulcare.com/patients/201/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@lab_report.pdf" \
  -F "type=lab_report" \
  -F "description=Blood test results"

Rate Limits

Patient search: 100 requests per hour
Patient updates: 50 per hour
Document uploads: 20 per hour (per patient)
Medical history updates: 30 per hour

Next Steps

Appointment APIs - Book and manage appointments
Medical Records APIs - Prescriptions and careplans
Billing APIs - Patient billing and payments

Patient APIs

OverviewCopy Anchor Link

EndpointsCopy Anchor Link

Patient Profile ManagementCopy Anchor Link

Get Patient ProfileCopy Anchor Link

Update Patient ProfileCopy Anchor Link

Get Current Patient ProfileCopy Anchor Link

Clinic-Specific Patient RecordsCopy Anchor Link

List Clinic PatientsCopy Anchor Link

Get Clinic Patient DetailsCopy Anchor Link

Register New PatientCopy Anchor Link

Update Clinic PatientCopy Anchor Link

Patient Medical HistoryCopy Anchor Link

Get Patient Medical HistoryCopy Anchor Link

Update Medical HistoryCopy Anchor Link

Patient Appointments HistoryCopy Anchor Link

Get Patient AppointmentsCopy Anchor Link

Patient Search & DiscoveryCopy Anchor Link

Search PatientsCopy Anchor Link

Patient Documents & FilesCopy Anchor Link

List Patient DocumentsCopy Anchor Link

Upload Patient DocumentCopy Anchor Link

Patient AnalyticsCopy Anchor Link

Get Patient StatisticsCopy Anchor Link

Error ResponsesCopy Anchor Link

Common Error CodesCopy Anchor Link

Example Error ResponseCopy Anchor Link

WebhooksCopy Anchor Link

ExamplesCopy Anchor Link

Complete Patient Registration FlowCopy Anchor Link

Rate LimitsCopy Anchor Link

Next StepsCopy Anchor Link

On this page

Overview

Endpoints

Patient Profile Management

Get Patient Profile

Update Patient Profile

Get Current Patient Profile

Clinic-Specific Patient Records

List Clinic Patients

Get Clinic Patient Details

Register New Patient

Update Clinic Patient

Patient Medical History

Get Patient Medical History

Update Medical History

Patient Appointments History

Get Patient Appointments

Patient Search & Discovery

Search Patients

Patient Documents & Files

List Patient Documents

Upload Patient Document

Patient Analytics

Get Patient Statistics

Error Responses

Common Error Codes

Example Error Response

Webhooks

Examples

Complete Patient Registration Flow

Rate Limits

Next Steps