Complete API Documentation for Developers

🚀 Quick Start

Step 1: Get Your API Key

  1. Log in to your MediTrak Healthcare Provider account
  2. Go to API Keys
  3. Click "Create New API Key"
  4. Give it a name (e.g., "My Application")
  5. Copy the key immediately (you won't see it again!)
⚠️ Security Notice: Never share your API key or commit it to version control. Store it securely in environment variables.

Step 2: Make Your First Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     http://meditrakapp.com/api/v1/invoices/

Expected Response:

{
  "success": true,
  "invoices": [
    {
      "invoice_id": "INV-2025-001",
      "patient_name": "John Doe",
      "total_amount": 1500.00,
      "status": "approved",
      "service_date": "2025-01-15"
    }
  ],
  "pagination": {
    "page": 1,
    "total_count": 45
  }
}

🔐 Authentication

All API requests require authentication using your API key in the Authorization header.

Method 1: Bearer Token (Recommended)

Authorization: Bearer YOUR_API_KEY
📘 Base URL: All endpoints are relative to: http://meditrakapp.com/api/v1/

📡 API Endpoints

GET /api/v1/invoices/

List Invoices

Retrieve a paginated list of all invoices for your healthcare facility.

Query Parameters:

Parameter Type Required Description
page integer No Page number (default: 1)
limit integer No Results per page (default: 50, max: 100)
status string No Filter by status: draft, submitted, approved, rejected, paid
date_from date No Start date (YYYY-MM-DD)
date_to date No End date (YYYY-MM-DD)

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://meditrakapp.com/api/v1/invoices/?status=approved&limit=100"
GET /api/v1/invoices/{invoice_id}/

Get Single Invoice

Retrieve detailed information about a specific invoice.

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     http://meditrakapp.com/api/v1/invoices/INV-2025-001/
GET /api/v1/invoices/stats/

Get Statistics

Get statistical information about your invoices.

Query Parameters:

Parameter Type Required Description
date_from date No Start date for statistics
date_to date No End date for statistics

Example:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "http://meditrakapp.com/api/v1/invoices/stats/?date_from=2025-01-01&date_to=2025-12-31"

Response:

{
  "success": true,
  "statistics": {
    "total_invoices": 150,
    "total_amount": 125000.00,
    "average_amount": 833.33,
    "by_status": {
      "approved": {"count": 80, "amount": 75000.00},
      "paid": {"count": 35, "amount": 27500.00}
    }
  }
}
POST /api/v1/invoices/export/bulk/

Bulk Export

Export multiple invoices at once with flexible filtering.

Request Body:

{
  "invoice_ids": ["INV-001", "INV-002"],  // optional
  "date_from": "2025-01-01",              // optional
  "date_to": "2025-01-31",                // optional
  "status": "approved"                    // optional
}
💡 Tip: All fields are optional. Empty body {} exports all invoices (up to 1000).

Example:

curl -X POST \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"status":"approved","date_from":"2025-01-01"}' \
     http://meditrakapp.com/api/v1/invoices/export/bulk/

💻 Code Examples

JavaScript / Node.js

const MEDITRAK_API_KEY = 'your_api_key_here';
const BASE_URL = 'http://meditrakapp.com/api/v1';

async function getInvoices() {
    const response = await fetch(`${BASE_URL}/invoices/`, {
        headers: {
            'Authorization': `Bearer ${MEDITRAK_API_KEY}`
        }
    });
    
    const data = await response.json();
    console.log(`Found ${data.invoices.length} invoices`);
    return data.invoices;
}

async function getStatistics(dateFrom, dateTo) {
    const url = new URL(`${BASE_URL}/invoices/stats/`);
    url.searchParams.append('date_from', dateFrom);
    url.searchParams.append('date_to', dateTo);
    
    const response = await fetch(url, {
        headers: {
            'Authorization': `Bearer ${MEDITRAK_API_KEY}`
        }
    });
    
    const data = await response.json();
    return data.statistics;
}

// Usage
getInvoices().then(invoices => {
    invoices.forEach(invoice => {
        console.log(`${invoice.invoice_id}: $${invoice.total_amount}`);
    });
});

Python

import requests

MEDITRAK_API_KEY = 'your_api_key_here'
BASE_URL = 'http://meditrakapp.com/api/v1'

class MediTrakAPI:
    def __init__(self, api_key):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            'Authorization': f'Bearer {api_key}'
        })
    
    def get_invoices(self, status=None, limit=50):
        """Get list of invoices"""
        params = {'limit': limit}
        if status:
            params['status'] = status
        
        response = self.session.get(
            f'{BASE_URL}/invoices/',
            params=params
        )
        response.raise_for_status()
        return response.json()['invoices']
    
    def get_statistics(self, date_from=None, date_to=None):
        """Get invoice statistics"""
        params = {}
        if date_from:
            params['date_from'] = date_from
        if date_to:
            params['date_to'] = date_to
        
        response = self.session.get(
            f'{BASE_URL}/invoices/stats/',
            params=params
        )
        response.raise_for_status()
        return response.json()['statistics']

# Usage
api = MediTrakAPI(MEDITRAK_API_KEY)
invoices = api.get_invoices(status='approved', limit=100)
print(f"Found {len(invoices)} approved invoices")

PHP

apiKey = $apiKey;
        $this->baseUrl = $baseUrl;
    }
    
    public function getInvoices($params = []) {
        $url = $this->baseUrl . '/invoices/';
        if (!empty($params)) {
            $url .= '?' . http_build_query($params);
        }
        
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiKey
        ]);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
}

// Usage
$api = new MediTrakAPI('your_api_key_here');
$invoices = $api->getInvoices(['status' => 'approved', 'limit' => 100]);
echo "Found " . count($invoices['invoices']) . " invoices\n";

?>

⚠️ Error Handling

401 Unauthorized

{
  "success": false,
  "error": "Invalid or expired API key",
  "code": "INVALID_API_KEY"
}

Solution: Check your API key is correct and active.

400 Bad Request

{
  "success": false,
  "error": "Invalid date format",
  "code": "INVALID_PARAMETER"
}

Solution: Verify request parameters match required format.

404 Not Found

{
  "success": false,
  "error": "Invoice not found",
  "code": "INVOICE_NOT_FOUND"
}

Solution: Check invoice ID exists and you have access.

📥 Invoice Import Requirements

Want MediTrak to import invoices from your system? Your API needs to provide these two endpoints with the data structure below.

✨ Automatic Processing: MediTrak automatically creates service categories, validates data, and organizes everything. No manual setup required.

Required Endpoints

GET /api/invoices

List all invoices with optional filtering by date range, status, or update time.

GET /api/invoices/{id}

Get a single invoice by ID.

Required JSON Structure

{
  "id": "INV-001",                    // ✅ Required: Unique invoice ID
  "invoice_number": "INV-2025-001",  // ✅ Required: Invoice number
  "invoice_date": "2025-01-15",      // ✅ Required: YYYY-MM-DD
  "total_amount": 1250.00,           // ✅ Required: Decimal (2 places)
  "status": "paid",                  // ✅ Required: paid/unpaid/pending
  "facility": "CFB Medical Hospital", // 📝 Recommended
  "patient": {
    "name": "John Doe",              // ✅ Required
    "policy_number": "POL-456789"    // ✅ Required: Must exist in MediTrak
  },
  "items": [                          // ✅ Required: At least 1 item
    {
      "category": "consultation",     // ✅ Required: See categories below
      "description": "General Consultation", // ✅ Required
      "quantity": 1,                  // ✅ Required
      "unit_price": 450.00,           // ✅ Required
      "total": 450.00                 // ✅ Required: quantity × unit_price
    },
    {
      "category": "laboratory",
      "description": "Full Blood Count",
      "quantity": 2,
      "unit_price": 400.00,
      "total": 800.00
    }
  ]
}

Standard Categories

Use these category values for items[].category:

Category Description Examples
consultationGeneral Consultation, Specialist Consultation, Follow-up
laboratoryFull Blood Count, Malaria Test, HIV Test, Urinalysis
radiologyX-Ray, Ultrasound, MRI Scan, CT Scan
pharmacyAntibiotics, Pain Medication, Insulin
emergencyEmergency Room Fee, Trauma Care
surgeryMinor Surgery, Wound Care, Sutures
dentalTooth Extraction, Cleaning, Root Canal
physiotherapyPhysiotherapy Session, Rehabilitation
obstetricsPrenatal Care, Ultrasound, Delivery
opticalEye Exam, Glasses, Contact Lenses
💡 New Categories: Don't see your category? No problem! MediTrak creates new categories automatically during import.

Key Requirements Summary

⚠️ Critical: The patient.policy_number field must match an existing policy in MediTrak. Contact our integration team to synchronize policy numbers before starting imports.

Testing Your Integration

Use these test credentials to verify your API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://your-api.com/api/invoices"

We'll test the connection and provide feedback on data structure compliance.

Ready to Start Building?

Get your API key and start integrating MediTrak into your application today!

Get Your API Key Try API Playground