API Documentation

Welcome to the WootHealth Backend API.

Authentication

API requests are authenticated using session cookies. The login and signup endpoints are available to create and authenticate a user.

Endpoints

POST /signup

Create a new user.

Body:

{
    "email": "user@example.com",
    "password": "password"
}

Flutter:

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<void> signup(String email, String password) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/signup'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'email': email,
      'password': password,
    }),
  );
  
  if (response.statusCode == 200 || response.statusCode == 201) {
    print('Signup successful');
  }
}

POST /login

Login a user.

Body:

{
    "email": "user@example.com",
    "password": "password"
}

Flutter:

Future<void> login(String email, String password) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/login'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'email': email,
      'password': password,
    }),
  );
  
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    print('Login successful');
  }
}

GET /providers

Get a list of providers.

GET /plans

Get the logged-in user's active plan, coverage summary, and quick actions.

Response (example):

{
    "success": true,
    "data": {
        "activePlan": {
            "name": "Retail Quantum Plan",
            "monthlyPremium": 34100,
            "coveredMembers": 4,
            "nextRenewal": "2025-01-10",
            "planType": "Family Coverage",
            "hmoId": "111076",
            "coverageActive": true
        },
        "coverageSummary": [
            {
                "title": "Hospital Care",
                "annualLimit": 5000000,
                "used": 450000,
                "utilizedPercent": 9
            },
            {
                "title": "Pharmacy & Drugs",
                "annualLimit": 500000,
                "used": 120000,
                "utilizedPercent": 24
            }
        ],
        "quickActions": [
            {"key": "reimbursement", "label": "Reimbursement"},
            {"key": "find_provider", "label": "Find a Provider"},
            {"key": "upgrade_plan", "label": "Upgrade Plan"},
            {"key": "add_dependent", "label": "Add Dependent"}
        ]
    }
}

GET /logout

Logout the current user.

Admin Endpoints

All admin endpoints support both GET (retrieve data) and POST (create/update data) methods. Base path: /admin/{feature}

GET POST /admin/overview

Manage overview dashboard data. GET returns total counts of users, enrollees, clients, and telemedicine requests.

GET POST /profile

User-facing profile management. GET retrieves current user's profile, POST updates current user's profile.

Body (POST):

{
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "specialization": "Cardiology",
    "availability": true
}

Flutter (GET):

Future<void> getProfile() async {
  final response = await http.get(
    Uri.parse('http://your-server.com/profile'),
    headers: {'Content-Type': 'application/json'},
  );
  
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    print('Profile: ${data["data"]}');
  }
}

Flutter (POST):

Future<void> updateProfile({
  required String email,
  required String phone,
  required String firstName,
  required String lastName,
}) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/profile'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'email': email,
      'phone': phone,
      'firstName': firstName,
      'lastName': lastName,
    }),
  );
  
  if (response.statusCode == 200) {
    print('Profile updated');
  }
}

GET POST /admin/profile

Admin-only profile management. GET retrieves any user's profile, POST creates or updates user profile (admin only).

Body (POST):

{
    "userId": "user_id",
    "email": "user@example.com",
    "password": "password",
    "phone": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "role": "doctor",
    "specialization": "Cardiology",
    "availability": true
}

GET POST /notifications

Manage user notifications. GET retrieves all notifications, POST creates new notification.

Body (POST):

{
    "notificationId": "unique_id",
    "message": "Notification message (max 500 characters)",
    "status": "pending",
    "notificationType": "alert",
    "priorityLevel": 3
}

Flutter (GET):

Future<void> getNotifications() async {
  final response = await http.get(
    Uri.parse('http://your-server.com/notifications'),
  );
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    List notifications = data['data'];
    print('Notifications: $notifications');
  }
}

Flutter (POST):

Future<void> createNotification({
  required String notificationId,
  required String message,
  required String status,
  required String notificationType,
  required int priorityLevel,
}) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/notifications'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'notificationId': notificationId,
      'message': message,
      'status': status,
      'notificationType': notificationType,
      'priorityLevel': priorityLevel,
    }),
  );
  if (response.statusCode == 201) {
    print('Notification created');
  }
}

Query Parameters:

GET /notifications/{id} - Get specific notification by ID
PUT /notifications/{id} - Update notification
DELETE /notifications/{id} - Delete notification

GET POST /messages

Manage appointment messages. GET retrieves all messages (optionally filter by appointmentId), POST creates new message.

Body (POST):

{
    "appointmentId": "appointment_id",
    "senderId": "user_id",
    "content": "Message content (max 1024 characters)",
    "type": "text"
}

Flutter (GET with filter):

Future<void> getMessages({String? appointmentId}) async {
  String url = 'http://your-server.com/messages';
  if (appointmentId != null) {
    url += '?appointmentId=$appointmentId';
  }
  final response = await http.get(Uri.parse(url));
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    List messages = data['data'];
    print('Messages: $messages');
  }
}

Flutter (POST):

Future<void> sendMessage({
  required String appointmentId,
  required String senderId,
  required String content,
}) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/messages'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'appointmentId': appointmentId,
      'senderId': senderId,
      'content': content,
      'type': 'text',
    }),
  );
  if (response.statusCode == 201) {
    print('Message sent');
  }
}

Query Parameters:

GET /messages?appointmentId=xxx - Filter by appointment
GET /messages/{id} - Get specific message
PUT /messages/{id} - Update message
DELETE /messages/{id} - Delete message

GET POST /callhistory

Manage call history records. GET retrieves all call records (optionally filter by appointmentId), POST creates new call history.

Body (POST):

{
    "appointmentId": "appointment_id",
    "durationSec": 3600,
    "startedAt": "2026-01-02T10:30:00Z",
    "endedAt": "2026-01-02T11:30:00Z"
}

Flutter (POST):

Future<void> createCallHistory({
  required String appointmentId,
  required int durationSec,
  required String startedAt,
  required String endedAt,
}) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/callhistory'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'appointmentId': appointmentId,
      'durationSec': durationSec,
      'startedAt': startedAt,
      'endedAt': endedAt,
    }),
  );
  if (response.statusCode == 201) {
    print('Call history recorded');
  }
}

Query Parameters:

GET /callhistory?appointmentId=xxx - Filter by appointment
GET /callhistory/{id} - Get specific call record
PUT /callhistory/{id} - Update call history
DELETE /callhistory/{id} - Delete call record

GET POST /recentactivity

Manage user activity logs. GET retrieves all activities for current user, POST logs new activity.

Body (POST):

{
    "activityType": "login",
    "description": "User logged in from mobile app (max 500 characters)",
    "metadata": {
        "ipAddress": "192.168.1.1",
        "device": "mobile"
    }
}

Flutter (GET):

Future<void> getRecentActivities() async {
  final response = await http.get(
    Uri.parse('http://your-server.com/recentactivity'),
  );
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    List activities = data['data'];
    print('Activities: $activities');
  }
}

Flutter (POST):

Future<void> logActivity({
  required String activityType,
  required String description,
  Map<String, dynamic>? metadata,
}) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/recentactivity'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'activityType': activityType,
      'description': description,
      if (metadata != null) 'metadata': metadata,
    }),
  );
  if (response.statusCode == 201) {
    print('Activity logged');
  }
}

Query Parameters:

GET /recentactivity/{id} - Get specific activity
DELETE /recentactivity/{id} - Delete activity

GET POST /patients

Manage patient records (doctor only). GET retrieves all patients handled by the doctor, POST adds/assigns a new patient.

Body (POST):

{
    "patientId": "unique_patient_id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "patient@example.com",
    "phone": "+1234567890",
    "medicalHistory": "Patient history (optional, max 1000 characters)",
    "allergies": "Penicillin (optional, max 500 characters)",
    "dateOfBirth": "1990-01-15",
    "gender": "male"
}

Flutter (GET with pagination):

Future<void> getPatients({int limit = 100, int offset = 0}) async {
  final response = await http.get(
    Uri.parse('http://your-server.com/patients?limit=$limit&offset=$offset'),
  );
  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    List patients = data['data'];
    int total = data['total'];
    print('Patients: $patients (Total: $total)');
  }
}

Flutter (POST):

Future<void> addPatient({
  required String patientId,
  required String firstName,
  required String lastName,
  required String email,
  required String phone,
  String? medicalHistory,
  String? allergies,
}) async {
  final response = await http.post(
    Uri.parse('http://your-server.com/patients'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({
      'patientId': patientId,
      'firstName': firstName,
      'lastName': lastName,
      'email': email,
      'phone': phone,
      if (medicalHistory != null) 'medicalHistory': medicalHistory,
      if (allergies != null) 'allergies': allergies,
    }),
  );
  if (response.statusCode == 201) {
    print('Patient added');
  }
}

Query Parameters:

GET /patients?limit=100&offset=0 - Get patients with pagination
GET /patients/{id} - Get specific patient
DELETE /patients/{id} - Remove patient from doctor's list
Note: Doctor role required; can only access own patients

Admin Endpoints

All admin endpoints support both GET (retrieve data) and POST (create/update data) methods. Base path: /admin/{feature}

All endpoints return JSON responses. GET requests from admin endpoints return:

{
    "success": true,
    "data": [],
    "total": 0,
    "message": "List retrieved"
}

Error Handling

Errors are returned with appropriate HTTP status codes and a JSON error message:

{
    "error": "Error description"
}