Clinical Master Portal

Exhaustive API specification for the GlucoCare clinical ecosystem.

🛑 ATTENTION: All routes requiring JWT must include "Authorization: Bearer <token>" in the header.

CONSULTANT MODE ENABLED

Doctors can monitor ALL patients via the /api/consultant gateway. All response payloads mirror the standard patient API but are optimized for professional clinical dashboards.

GUARDIAN PROTOCOL ACTIVE

Next of Kin users can monitor patient data by adding ?userId={patientId} to retrieval endpoints (Readings, Meals, Alerts, etc). Verified via Email/Phone credentials.

Gateways & Sessions

Payload Sample

{
    "displayName": "John Doe",
    "email": "john@gluco.care",
    "phone": "09012345678",
    "password": "securePass123",
    "role": "patient"
}

NOTE

Supports 'patient', 'next_of_kin', and 'doctor' roles. Phone numbers are automatically normalised to E.164.

Payload Sample

{ 
    "identifier": "john@gluco.care", 
    "password": "securePass123" 
}

UNIVERSAL LOGIN

Input 'identifier' can be either an Email address or a Phone number (in any Nigerian format).

TOKEN ROTATION

Refresh your JWT before it expires. Requires the current token in the Authorization header.

LIGHTWEIGHT IDENTITY

Returns basic ID card: uid, displayName, email, role. No clinical profile data included.

TERMINATE

Blacklists the current JWT.

Security Recovery (OTP)

2-STEP OTP FLOW

Step 1: Request OTP → sent to email + SMS. Step 2: Submit OTP to get a signed reset token. Step 3: POST new password using the reset token. Each OTP expires in 10 minutes.

{ "email": "john@gluco.care" }

STEP 1

Generates a random 6-digit OTP and delivers it via Email + SMS. OTP is valid for 10 minutes.

{ "email": "john@gluco.care", "otp": "482916" }

STEP 2

Validates the OTP. On success, returns a reset_token (a signed URL valid for 15 min). OTP is immediately invalidated after use — cannot be reused.

{ "password": "newSecurePassword123" }

🔒 SIGNED RESET TOKEN REQUIRED (from verify-otp response)

STEP 3

Use the full reset_token URL returned by verify-otp as the request URL. The token is a signed Laravel URL that contains the user ID and expires in 15 minutes.

Email Verification

HOW IT WORKS

A "Verify My Email" button is embedded in the welcome email on registration. Clicking it calls the endpoint below and sets email_verified_at on the user record. The emailVerified flag is returned on every login/register response.

🔒 SIGNED URL REQUIRED (embedded in welcome email)

EMAIL CONFIRMED

Called automatically when user clicks the link in the welcome email. Sets email_verified_at = now(). Link is valid for 72 hours from registration.

Doctor Portal: Credentials & Identity

🔒 DOCTOR ROLE REQUIRED

Payload Sample

{ 
    "displayName": "Dr. John Doe", 
    "organization": "Apex Medical Group", 
    "hospital_affiliation": "St. Jude Hospital",
    "contact_email": "dr.john@apexmedical.com",
    "specialization": "Endocrinologist",
    "experience_years": 15,
    "license_number": "MD-459021-AX",
    "bio": "Specializing in Type 1 Diabetes management.",
    "consultation_fee": "$150/hr",
    "availability_status": "available"
}

🔒 DOCTOR ROLE REQUIRED

Doctor Portal: Discovery

🔒 DOCTOR ROLE REQUIRED

NOTE

Lists all metabolic patients. Supports ?search=... for name/email lookup. Paginated by default.

🔒 DOCTOR ROLE REQUIRED

NOTE

Gets full patient profile, including Bio-Targets and Next of Kin contact records.

Doctor Portal: Clinical Oversight

🔒 DOCTOR ROLE REQUIRED

NOTE

Returns patient Tir (Time in Range), estimated HbA1c, and trend analytics.

🔒 DOCTOR ROLE REQUIRED

NOTE

Generates an exhaustive Unified Health Report for medical consultation.

Clinical Comms: Infinite Threads

The hyper-scale, zero-join continuous messaging ecosystem. Completely symmetric for both Doctors and Patients.

🔒 ROLE AGNOSTIC (Patient or Doctor)

CACHED INBOX

Returns the zero-join hyper-fast inbox counting badges and snippets natively in milliseconds.

{ "targetUserId": "uuid-here" }

🔒 ROLE AGNOSTIC (Patient or Doctor)

NO DUPLICATES

Returns a brand new conversationId or instantly retrieves the existing infinite thread container. Always run this before chatting a new person!

🔒 ROLE AGNOSTIC (Patient or Doctor)

INFINITE SCROLLING

Returns chat bubbles (50 per page). Leverages B-Tree indexing to ensure loading page 20 is just as fast as page 1.

{ "content": "Hello doctor, my glucose spiked." }

🔒 ROLE AGNOSTIC (Patient or Doctor)

BLUE TICKS

Fired when opening the chat screen. Marks other person's bubbles as read, and wipes the unread inbox badge back to zero!

Role-Aware Profile Management

🔒 JWT REQUIRED

AUTO-RESOLVE

Returns your central identity PLUS your role-specific profile (patient, doctor, or next_of_kin) and baseline clinical vitals if applicable.

Update Generic & Patient Profile

{
    "displayName": "John Updated Doe",
    "phone": "09012345678",
    "diabetes_type": "type2",
    "baseline_weight_kg": 85.5,
    "baseline_glucose_mg_dl": 110,
    "theme": "dark",
    "notification": true
}

🔒 JWT REQUIRED

DYNAMIC VALIDATION

The API intelligently maps shared fields (name/phone) to the user table while routing clinical vitals to specialized profile tables.

🔒 JWT REQUIRED

DATA PORTABILITY

Generates a JSON dump of all user data.

🔒 JWT REQUIRED

Payload Sample

{ 
    "displayName": "Jane Doe", 
    "relationship": "Spouse", 
    "phone": "09012345678",
    "email": "jane@example.com",
    "address": "123 Clinical St.",
    "isEmergencyContact": true
}

🔒 JWT REQUIRED

GUARDIAN ACTIVATION

Adding a NOK with a valid email allows that person to register/login and monitor your metabolic data.

🔒 JWT REQUIRED

App Preferences

User-level settings stored on the users table. All auth responses (login, register, /me) already include the current preference state.

Payload Sample

{
    "theme": "light",
    "biometric": true,
    "notification": true,
    "notification_token": "fcm_or_apns_device_token_here"
}

🔒 JWT REQUIRED

FIELDS

theme — "light" or "dark" (default: dark)
biometric — true/false. Mobile app fingerprint / face-id flag.
notification — true/false. Master toggle for all push and in-app alerts.
notification_token — FCM (Android) or APNS (iOS) push device token. Store on app start/login.

Glucose Tracking

{ "valueMgDl": 120, "context": "fasting", "recordedAt": "2026-04-03T07:00:00Z" }

🔒 JWT REQUIRED

NOTE

Accepts ?userId=... ?from=... ?to=... for guardian oversight.

🔒 JWT REQUIRED

Medication Matrix

Payload Sample

{ 
    "name": "Metformin", 
    "doseMg": 500, 
    "doseUnit": "mg", 
    "type": "tablet",
    "scheduleTimes": [{"hour": 8, "minute": 0}, {"hour": 20, "minute": 0}],
    "mealTiming": "after_meal"
}

🔒 JWT REQUIRED

NOTE

Returns current active prescriptions. Supports ?activeOnly=true.

🔒 JWT REQUIRED

Adherence Logs

{ "scheduledTime": {"hour": 8, "minute": 0}, "skipped": false }

🔒 JWT REQUIRED

DAILY AGENDA

Returns what doses are pending or completed for a specific date (?date=2024-04-05).

Dietary Intelligence

{ "name": "Oatmeal", "mealType": "breakfast", "carbsG": 45, "proteinG": 10, "fatG": 5, "calories": 300, "loggedAt": "2026-04-03T07:30:00Z" }

🔒 JWT REQUIRED

NOTE

Returns summary totals and daily averages for the requested period.

🔒 JWT REQUIRED

WEEKLY PLAN

Returns the full 7-day Nigerian diabetic meal plan.

🔒 JWT REQUIRED

FORM-DATA PARAMETERS (Postman Matrix)

KEY	TYPE	VALUE (EXAMPLE)
day	Text	MONDAY
meal_type	Text	Lunch
content	Text	Nigerian Salad with fish and garden egg.
image	File	(Select salad.jpg asset)

🔒 DOCTOR ROLE REQUIRED

STRICT VALIDATION

Permitted formats: jpeg, png, jpg, webp. Maximum size: 2,048 KB (2MB).

🔒 DOCTOR ROLE REQUIRED

Fitness Analytics

{ "type": "walking", "durationMinutes": 30, "caloriesBurned": 150, "intensity": "moderate", "loggedAt": "2026-04-03T18:00:00Z" }

🔒 JWT REQUIRED

Health Notifications

Payload Sample

{
    "title": "Abnormal Glucose Detected",
    "message": "Fasting glucose of 250 mg/dL is critically high.",
    "severity": "critical"
}

🔒 JWT REQUIRED

NOTE

Accepts ?userId=... ?unreadOnly=true for guardian monitoring. Severity can be filtered via ?severity=critical.

🔒 JWT REQUIRED

Payload Sample

{ "title": "Meal Reminder", "message": "It's time for lunch!", "user_id": "(optional uuid)" }

🔒 JWT REQUIRED

CUSTOM PUSH API (MOBILE)

Allows the mobile app to trigger a custom Firebase push notification instantly. If user_id is omitted, it sends the push to the authenticated user. Otherwise, it sends to the specified user. Respects the target user's notification preference.

🔒 JWT REQUIRED

Retrieves a paginated list of all in-app database notifications stored via web-alert.

Knowledge & Reporting

🔒 JWT REQUIRED

{ "title": "New Research", "category": "education", "content": "# Markdown Content" }

🔒 DOCTOR ROLE REQUIRED

{ "question": "Why water?", "answer": "Hydration." }

🔒 DOCTOR ROLE REQUIRED

ADMIN DISCARD

Permits removal of education/clinical resources.

🔒 JWT REQUIRED

NOTE

Supports ?userId=... for guardians to generate medical dossiers.

OFFLINE SYNC

Bulk upload offline readings, logs, and meal data.