REST API · v1

The health platform
built for Africa

A secure, scalable API connecting patients with verified practitioners through personalised health plans, live consultations, and intelligent recommendations.

Get started View endpoints
40+ API modules
JWT Auth standard
Real-time WebSocket + Socket.io
99.9% Target uptime

Platform capabilities

Everything your health app needs

From identity and compliance to intelligent recommendations — all on one platform.

🧑‍⚕️
Practitioner Profiles
Verified health practitioners with rich profiles, specialisations, availability schedules, ratings, and certification management.
Practitioners
📋
Health Plans
Create, manage, and subscribe to structured health plans with activities, schedules, progress tracking, and flexible pricing.
Health Plans
📞
Live Consultations
Agora-powered audio and video calls with session management, recording support, and real-time status tracking.
Calls
💬
Secure Messaging
End-to-end chat between patients and practitioners with media sharing, read receipts, and conversation threading.
Chat
🧠
AI Recommendations
pgvector-powered recommendation engine using behavioural signals, embeddings, and hybrid ranking to surface the right practitioners and plans.
Recommendations
🔒
Compliance & Security
RBAC with roles, permissions, and policies. Audit logs, device trust management, and multi-factor authentication built in.
Security
💳
Payments & Wallets
Flutterwave-integrated payments with wallet management, subscription tiers, payouts, and full transaction history.
Commerce
🔔
Notifications
Multi-channel notifications (push, email, in-app) with priority queuing, scheduling, and per-user preferences via BullMQ.
Notifications
📊
Surveys & Streams
Configurable health surveys, live health streams with audience management, and rich analytics across all engagement touchpoints.
Engagement

REST API

Core endpoints

All routes are prefixed with /api/v1

👤 Auth
POST/auth/register
POST/auth/login
POST/auth/refresh-token
POST/auth/logout
POST/auth/forgot-password
POST/auth/verify-otp
🧑 Users
GET/users/me
PUT/users/me
GET/users/:id
POST/onboarding
GET/settings
PUT/settings
📋 Health Plans
GET/health-plans
POST/health-plans
GET/health-plans/:id
PUT/health-plans/:id
POST/health-plans/:id/subscribe
GET/health-plans/:id/activities
📞 Calls & Chat
POST/calls/initiate
POST/calls/join
GET/calls/history
GET/chat/conversations
POST/chat/send
GET/chat/:id/messages
🧠 Recommendations
GET/recommendations
GET/search
GET/screen
POST/ratings
GET/ratings/:id
GET/lookup
💳 Commerce
GET/plans
GET/wallet
POST/payment/initiate
GET/subscriptions
GET/referrals
GET/referral-codes

Quickstart

Up and running in minutes

Authenticate once, then access the full platform. Here's a complete register → login → query flow.

HTTP Request 
# 1. Register a new user
POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "patient@example.com",
  "password": "Secure@Pass1",
  "userType": "PATIENT"
}

# 2. Login to get tokens
POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "patient@example.com",
  "password": "Secure@Pass1"
}

# 3. Fetch health plans
GET /api/v1/health-plans
Authorization: Bearer <accessToken>
JSON Response 
{
  "status": "success",
  "data": {
    "accessToken": "eyJhbGci...",
    "refreshToken": "eyJhbGci...",
    "user": {
      "id": "uuid-v4",
      "email": "patient@...",
      "userType": "PATIENT",
      "isEmailVerified": false
    }
  },
  "message": "Login successful"
}

// Health plans list
{
  "status": "success",
  "data": {
    "plans": [...],
    "pagination": {
      "total": 42,
      "page":  1,
      "limit": 10
    }
  }
}