Patients API

2026-02-01 · 4 min

Overview

The Patients API provides CRUD operations for patient demographics, search, and medical record access. Use this API to integrate external systems (mobile apps, kiosks, third-party portals) with Bio Ecko's patient database.

List Patients

GET /api/v1/patients

Query parameters:

• page (int): Page number, default 1.
• per_page (int): Results per page, default 20, max 100.
• search (string): Search by name, phone, patient ID, or ABHA ID.
• branch_id (string): Filter by branch.
• registered_after (date): Filter by registration date.

Response: Array of patient summary objects (id, name, phone, age, gender, patient_id, last_visit_date).

Get Patient

GET /api/v1/patients/{id}

Returns the full patient profile including:

• Demographics: Name, date of birth, gender, address, contact.
• Identifiers: Patient ID, ABHA ID, Aadhaar (masked), insurance details.
• Medical summary: Active diagnoses, allergies, current medications.
• Visit history: List of OPD and IPD visits with dates and providers.

Requires patients:read scope.

Create Patient

POST /api/v1/patients

Request body (JSON): { "first_name": "Rajesh", "last_name": "Kumar", "date_of_birth": "1985-03-15", "gender": "male", "phone": "+919876543210", "email": "rajesh@example.com", "address": { "line1": "...", "city": "Mumbai", "state": "Maharashtra", "pincode": "400001" }, "blood_group": "B+" }

Response: Created patient object with auto-generated patient_id. Requires patients:write scope.

Update Patient

PATCH /api/v1/patients/{id}

Send only the fields you want to update. All other fields remain unchanged.

Response: Updated patient object. Requires patients:write scope.

Error Handling

Standard error responses:

• 400 Bad Request: Invalid input (missing required field, invalid format). Response includes field-level error details.
• 401 Unauthorized: Missing or invalid token.
• 403 Forbidden: Token doesn't have required scope.
• 404 Not Found: Patient ID doesn't exist.
• 409 Conflict: Duplicate patient detected (matching phone + DOB).
• 429 Too Many Requests: Rate limit exceeded.
• 500 Internal Server Error: Unexpected error (report to support).

Notes

Related topics