DeveloperPatients
Patient History APIs
This document covers the patient history log endpoints for retrieving clinical events and activities.
Authentication
All patient history endpoints require authentication. Include the JWT token in the Authorization header:
Authorization: Bearer YOUR_AUTH_TOKENBase URL
/clinicalEndpoints Overview
| Method | Endpoint | Description |
|---|---|---|
| GET | /clinical/patients/:patient_id/patient_histories | List histories for a specific patient |
List Patient Histories
GET /clinical/patients/:patient_id/patient_histories
Retrieve patient history logs with optional filtering and pagination.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
patient_id | UUID | No | Patient ID (already in URL) | 019c9411-f78f-77c6-85e3-84b2b87e1dbb |
facility_id | UUID | No | Filter by facility | 01900002-0000-7000-8000-000000000001 |
key | String | No | Filter by history type | APPOINTMENT, ENCOUNTER, PRESCRIPTION |
practitioner_id | UUID | No | Filter by practitioner | 01900004-0000-7000-8000-000000000004 |
start_date | Date | No | Filter by date range (start) | 2026-01-01 |
end_date | Date | No | Filter by date range (end) | 2026-01-31 |
page | Integer | No | Page number (default: 1) | 1 |
per_page | Integer | No | Items per page (default: 25, max: 100) | 25 |
Filter Values (key parameter)
Available history types for filtering:
| Key | Description |
|---|---|
APPOINTMENT | Appointment events |
ENCOUNTER | Consultation/encounter events |
PRESCRIPTION | Prescription events |
OBSERVATION | Observation/vitals events |
NOTE | Clinical notes |
LAB_REPORT | Laboratory reports |
IMMUNISATION | Immunization records |
ALLERGY | Allergy records |
CONDITION | Medical conditions |
CARE_PLAN | Care plan events |
GOAL | Treatment goals |
MEDICATION_REQUEST | Medication requests |
DIAGNOSTIC_REPORT | Diagnostic reports |
VITALS | Vital signs |
PATIENT_PHOTO | Patient photos |
SHARED_RECORD | Shared medical records |
TELEMEDICINE_PRESCRIPTION | Telemedicine prescriptions |
THERAPY_NOTES | Therapy notes |
DERMA_EXAMINATION | Dermatology examinations |
NEURO_EXAMINATION | Neurology examinations |
CARDIO_EXAMINATION | Cardiology examinations |
DENTAL_EXAMINATION | Dental examinations |
MEDICAL_RECORD | Medical records |
Example Request
# Using query parameter
curl -X GET "https://api.kulcare.com/clinical/patient_histories?patient_id=019c9411-f78f-77c6-85e3-84b2b87e1dbb&key=APPOINTMENT&start_date=2026-01-01&end_date=2026-01-31" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN"
# Using nested route
curl -X GET "https://api.kulcare.com/clinical/patients/019c9411-f78f-77c6-85e3-84b2b87e1dbb/patient_histories?per_page=50" \
-H "Authorization: Bearer YOUR_AUTH_TOKEN"Response
{
"data": {
"patient": {
"id": "019c9411-f78f-77c6-85e3-84b2b87e1dbb",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"gender": "male",
"date_of_birth": "1990-01-15",
"phone_number": "+919999999999",
"created_at": "2025-01-01T00:00:00Z"
},
"histories": [
[
{
"id": "019c9411-f78f-77c6-85e3-84b2b87e1dbc",
"key": "APPOINTMENT",
"activity_ts": "2026-02-26T10:57:55.000000Z",
"activity_data": {
"id": "019c9411-f78f-77c6-85e3-84b2b87e1dba",
"status": "arrived",
"appointment_type": "walk_in",
"start_time": "2026-02-26T10:57:55.000000Z",
"end_time": null
},
"practice_viewable": true,
"patient_viewable": true
}
],
[
{
"id": "019c9411-f78f-77c6-85e3-84b2b87e1dbd",
"key": "ENCOUNTER",
"activity_ts": "2026-02-25T09:30:00.000000Z",
"activity_data": {
"id": "019c9411-f78f-77c6-85e3-84b2b87e1db9",
"status": "completed",
"encounter_type": "consultation"
},
"practice_viewable": true,
"patient_viewable": true
}
]
]
},
"meta": {
"pagination": {
"current_page": 1,
"next_page": null,
"prev_page": null,
"total_pages": 1,
"total_count": 2
}
}
}Response Fields
| Field | Type | Description |
|---|---|---|
data.patient | Object | Patient information (from PatientBlueprint) |
data.histories | Array[Array] | Array of daily grouped history logs |
data.histories[].id | UUID | Unique history log ID |
data.histories[].key | String | History type (e.g., APPOINTMENT, ENCOUNTER) |
data.histories[].activity_ts | DateTime | Timestamp of the activity |
data.histories[].activity_data | Object | Type-specific activity data |
data.histories[].practice_viewable | Boolean | Whether visible to practice |
data.histories[].patient_viewable | Boolean | Whether visible to patient |
meta.pagination | Object | Pagination metadata |
Activity Data by History Type
APPOINTMENT
{
"id": "uuid",
"status": "arrived",
"appointment_type": "walk_in",
"start_time": "2026-02-26T10:57:55.000000Z",
"end_time": null
}ENCOUNTER
{
"id": "uuid",
"status": "completed",
"encounter_type": "consultation",
"start_time": "2026-02-25T09:30:00.000000Z",
"end_time": "2026-02-25T10:00:00.000000Z"
}PRESCRIPTION / MEDICATION_REQUEST
{
"id": "uuid",
"status": "active",
"medications": [
{
"name": "Paracetamol",
"dosage": "500mg",
"frequency": " thrice a day",
"duration": "5 days"
}
]
}OBSERVATION / VITALS
{
"id": "uuid",
"type": "vitals",
"data": {
"blood_pressure": "120/80",
"heart_rate": 72,
"temperature": 98.6
}
}Error Responses
404 Not Found
{
"errors": [
{
"message": "Patient not found"
}
]
}401 Unauthorized
{
"errors": [
{
"message": "Authentication required"
}
]
}