API Reference

Complete REST API documentation for the MediPact backend.

Base URL

1http://localhost:8080

All API endpoints are prefixed with the base URL. For production, replace with your production API URL.

Interactive Documentation

Swagger UI

For interactive API documentation with request/response examples, visit:

1http://localhost:8080/api-docs

The Swagger UI provides a complete interface to explore all endpoints, test requests, and view response schemas.

Authentication

Hospital Authentication

Hospitals authenticate using hospital_id and api_key:

1POST /api/hospital/login
2Content-Type: application/json
3
4{
5  "hospitalId": "HOSP-001",
6  "apiKey": "your-api-key"
7}

Researcher Authentication

Researchers authenticate using researcher_id:

1POST /api/researcher/login
2Content-Type: application/json
3
4{
5  "researcherId": "RES-001"
6}

Patient Endpoints

Register Patient

1POST /api/patient/register
2Content-Type: application/json
3
4{
5  "name": "John Doe",
6  "dateOfBirth": "1990-01-15",
7  "gender": "male",
8  "hospitalId": "HOSP-001"
9}

Get Patient by UPI

1GET /api/patient/:upi

Hospital Endpoints

Register Hospital

1POST /api/hospital/register
2Content-Type: application/json
3
4{
5  "name": "City Hospital",
6  "email": "admin@cityhospital.com",
7  "country": "Uganda"
8}

Submit Verification Documents

1POST /api/hospital/verification
2Authorization: Bearer {api_key}
3Content-Type: multipart/form-data
4
5{
6  "licenseDocument": File,
7  "registrationCertificate": File,
8  "additionalDocuments": File[]
9}

Researcher Endpoints

Register Researcher

1POST /api/researcher/register
2Content-Type: application/json
3
4{
5  "email": "researcher@university.edu",
6  "organizationName": "University Research Lab",
7  "contactName": "Dr. Jane Smith",
8  "country": "Uganda"
9}

Submit Verification Documents

1POST /api/researcher/:researcherId/verify
2Content-Type: multipart/form-data
3
4{
5  "registrationNumber": "REG-12345",
6  "organizationDocuments": File,
7  "researchLicense": File,
8  "additionalDocuments": File[]
9}

Marketplace Endpoints

Browse Datasets

1GET /api/marketplace/datasets
2Query Parameters:
3  ?country=Uganda
4  &hospitalId=HOSP-001
5  &limit=50
6  &offset=0

Query Datasets

1POST /api/marketplace/query
2Content-Type: application/json
3
4{
5  "researcherId": "RES-001",
6  "filters": {
7    "country": "Uganda",
8    "startDate": "2024-01-01",
9    "endDate": "2024-12-31",
10    "conditionCode": "E11.9",
11    "gender": "male",
12    "ageRange": "35-50"
13  },
14  "limit": 100,
15  "preview": false
16}

Purchase Dataset

Purchase flow with payment verification:

1# Step 1: Initiate purchase (without transaction ID)
2POST /api/marketplace/purchase
3Content-Type: application/json
4
5{
6  "researcherId": "RES-001",
7  "datasetId": "DS-ABC123",
8  "amount": 100.00
9}
10
11# Response (202 Accepted):
12{
13  "paymentRequest": {
14    "paymentRequestId": "PAY-123",
15    "amountHBAR": 625.0,
16    "amountUSD": 100.00,
17    "recipientAccountId": "0.0.1234567",
18    "memo": "MediPact Dataset Purchase",
19    "instructions": "Send HBAR to the recipient account..."
20  },
21  "message": "Payment required",
22  "nextStep": "Send HBAR and provide transaction ID"
23}
24
25# Step 2: Complete purchase with transaction ID
26POST /api/marketplace/purchase
27Content-Type: application/json
28
29{
30  "researcherId": "RES-001",
31  "datasetId": "DS-ABC123",
32  "amount": 100.00,
33  "transactionId": "0.0.123@1234567890.123456789"
34}
35
36# Response (200 OK):
37{
38  "message": "Purchase successful",
39  "purchaseId": "PURCHASE-123",
40  "amountHBAR": 625.0,
41  "amountUSD": 100.00,
42  "transactionId": "0.0.123@1234567890.123456789",
43  "verified": true,
44  "revenueDistribution": {...},
45  "accessGranted": true,
46  "downloadUrl": "/api/marketplace/datasets/DS-ABC123/export"
47}

Wallet & Payment Endpoints

Get Wallet Balance

1# Patient wallet
2GET /api/patient/:upi/wallet
3
4# Hospital wallet
5GET /api/hospital/:hospitalId/wallet
6
7# Response:
8{
9  "balanceHBAR": 784.3750,
10  "balanceUSD": 125.50,
11  "hederaAccountId": "0.0.1234567",
12  "evmAddress": "0x...",
13  "paymentMethod": "bank",
14  "bankName": "Bank of Uganda",
15  "withdrawalThresholdUSD": 10.00,
16  "autoWithdrawEnabled": true
17}

Initiate Withdrawal

1# Patient withdrawal
2POST /api/patient/:upi/withdraw
3Content-Type: application/json
4
5{
6  "amountUSD": 100.00
7}
8
9# Hospital withdrawal
10POST /api/hospital/:hospitalId/withdraw
11Content-Type: application/json
12
13{
14  "amountUSD": 500.00
15}
16
17# Response:
18{
19  "message": "Withdrawal initiated successfully",
20  "withdrawal": {
21    "id": 123,
22    "amountHBAR": 625.0,
23    "amountUSD": 100.00,
24    "payment_method": "bank",
25    "destination_account": "1234****5678",
26    "status": "pending",
27    "created_at": "2024-01-15T10:30:00Z"
28  }
29}

Get Withdrawal History

1# Patient withdrawal history
2GET /api/patient/:upi/withdrawal-history?limit=10&offset=0
3
4# Hospital withdrawal history
5GET /api/hospital/:hospitalId/withdrawal-history?limit=10&offset=0

Update Payment Method

1# Patient payment method
2PUT /api/patient/:upi/payment-method
3Content-Type: application/json
4
5{
6  "paymentMethod": "bank",
7  "bankName": "Bank of Uganda",
8  "bankAccountNumber": "1234567890",
9  "withdrawalThresholdUSD": 10.00,
10  "autoWithdrawEnabled": true
11}
12
13# Hospital payment method
14PUT /api/hospital/:hospitalId/payment-method
15Content-Type: application/json
16
17{
18  "paymentMethod": "mobile_money",
19  "mobileMoneyProvider": "MTN",
20  "mobileMoneyNumber": "+256123456789",
21  "withdrawalThresholdUSD": 100.00,
22  "autoWithdrawEnabled": true
23}

Admin Endpoints

Admin endpoints for managing hospital and researcher verifications, viewing documents, and system administration.

Verification Workflow

Admin Authentication

All admin endpoints require JWT authentication. Include the token in the Authorization header for all requests.

1POST /api/admin/auth/login
2Content-Type: application/json
3
4{
5  "username": "admin",
6  "password": "admin-password"
7}
8
9# Response:
10{
11  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
12  "admin": {
13    "id": "admin-001",
14    "username": "admin"
15  }
16}

Use the token in subsequent requests: Authorization: Bearer {token}

List All Hospitals

Retrieve all hospitals with their verification status and document submission status. Hospitals are categorized by verification status (pending/verified/rejected) and whether they have submitted documents.

1GET /api/admin/hospitals
2Authorization: Bearer {token}
3
4# Response:
5{
6  "hospitals": [
7    {
8      "hospitalId": "HOSP-001",
9      "name": "City Hospital",
10      "country": "Uganda",
11      "location": "Kampala",
12      "contactEmail": "admin@cityhospital.com",
13      "verificationStatus": "pending",
14      "verificationDocuments": {
15        "licenseNumber": "HOSP-12345",
16        "registrationCertificate": "data:application/pdf;base64,..."
17      },
18      "registeredAt": "2024-01-15T10:30:00Z",
19      "status": "active"
20    }
21  ]
22}

Note: Hospitals without submitted documents will have verificationDocuments: null. Only hospitals with actual document content (license number, certificate, etc.) will have the documents object populated.

Get Hospital Details

Retrieve detailed information about a specific hospital, including full verification documents. Documents can be base64-encoded PDFs/images (data URLs) or external URLs.

1GET /api/admin/hospitals/:hospitalId
2Authorization: Bearer {token}
3
4# Response:
5{
6  "hospitalId": "HOSP-001",
7  "name": "City Hospital",
8  "country": "Uganda",
9  "location": "Kampala",
10  "contactEmail": "admin@cityhospital.com",
11  "fhirEndpoint": "https://fhir.example.com/fhir",
12  "registrationNumber": "HOSP-12345",
13  "verificationStatus": "pending",
14  "verificationDocuments": {
15    "licenseNumber": "HOSP-12345",
16    "registrationCertificate": "data:application/pdf;base64,JVBERi0yLjAK..."
17  },
18  "registeredAt": "2024-01-15T10:30:00Z",
19  "status": "active",
20  "paymentMethod": "bank",
21  "bankName": "Bank of Uganda"
22}

Document Formats: Registration certificates can be:

Data URLs: data:application/pdf;base64,... (base64-encoded PDFs)
External URLs: https://example.com/certificate.pdf (publicly accessible links)

Approve Hospital Verification

Approve a hospital's verification request. The hospital will be notified and gain full access to register patients and use all platform features.

1POST /api/admin/hospitals/:hospitalId/verify
2Authorization: Bearer {token}
3Content-Type: application/json
4
5{
6  "message": "Optional approval message for internal notes"
7}
8
9# Response:
10{
11  "success": true,
12  "hospital": {
13    "hospitalId": "HOSP-001",
14    "name": "City Hospital",
15    "verificationStatus": "verified",
16    "verifiedAt": "2024-01-16T14:30:00Z",
17    "verifiedBy": "admin-001"
18  }
19}

Reject Hospital Verification

Reject a hospital's verification request with a reason. The hospital will be notified and can resubmit documents after addressing the issues.

1POST /api/admin/hospitals/:hospitalId/reject
2Authorization: Bearer {token}
3Content-Type: application/json
4
5{
6  "reason": "Required: Reason for rejection (e.g., 'Invalid license number', 'Certificate expired')"
7}
8
9# Response:
10{
11  "success": true,
12  "hospital": {
13    "hospitalId": "HOSP-001",
14    "name": "City Hospital",
15    "verificationStatus": "rejected",
16    "verifiedBy": "admin-001"
17  }
18}

Important: The rejection reason will be visible to the hospital and should be clear and constructive to help them address the issues.

List All Researchers

Retrieve all researchers with their verification status and document submission status.

1GET /api/admin/researchers
2Authorization: Bearer {token}
3
4# Response:
5{
6  "researchers": [
7    {
8      "researcherId": "RES-001",
9      "email": "researcher@university.edu",
10      "organizationName": "University Research Lab",
11      "contactName": "Dr. Jane Smith",
12      "country": "Uganda",
13      "verificationStatus": "pending",
14      "verificationDocuments": {
15        "organizationDocuments": "data:application/pdf;base64,..."
16      },
17      "registeredAt": "2024-01-15T10:30:00Z",
18      "accessLevel": "basic"
19    }
20  ],
21  "total": 10
22}

Get Researcher Details

1GET /api/admin/researchers/:researcherId
2Authorization: Bearer {token}
3
4# Response includes full researcher information and verification documents

Approve Researcher Verification

1POST /api/admin/researchers/:researcherId/verify
2Authorization: Bearer {token}
3Content-Type: application/json
4
5{
6  "message": "Optional approval message"
7}
8
9# Response:
10{
11  "message": "Researcher verified successfully",
12  "researcher": {
13    "researcherId": "RES-001",
14    "verificationStatus": "verified",
15    "verifiedAt": "2024-01-16T14:30:00Z",
16    "verifiedBy": "admin-001"
17  }
18}

Reject Researcher Verification

1POST /api/admin/researchers/:researcherId/reject
2Authorization: Bearer {token}
3Content-Type: application/json
4
5{
6  "reason": "Required: Reason for rejection"
7}
8
9# Response:
10{
11  "message": "Researcher verification rejected",
12  "researcher": {
13    "researcherId": "RES-001",
14    "verificationStatus": "rejected",
15    "verifiedBy": "admin-001"
16  }
17}

Hedera Integration Endpoints

Get HCS Messages

1GET /api/hedera/messages?topicId=0.0.123456&limit=100

Get Transaction Details

1GET /api/hedera/transactions/:transactionId

Error Responses

All error responses follow this format:

1{
2  "error": "Error message description",
3  "code": "ERROR_CODE"
4}

Common Status Codes:

400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
500 - Internal Server Error