agdar/API_ENDPOINTS.md

Tenhal Healthcare Platform - API Documentation

Base URL

http://localhost:8000/api/v1/

Authentication

Currently using Django Session Authentication (DRF Browsable API).

Future: Token authentication will be added for mobile apps.

API Endpoints

🏥 Core Module

Patients

GET    /api/v1/patients/                    - List all patients
POST   /api/v1/patients/                    - Create new patient
GET    /api/v1/patients/{id}/               - Get patient details
PATCH  /api/v1/patients/{id}/               - Update patient
DELETE /api/v1/patients/{id}/               - Soft delete patient
GET    /api/v1/patients/{id}/files/         - Get patient files
GET    /api/v1/patients/{id}/consents/      - Get patient consents
GET    /api/v1/patients/{id}/audit_trail/   - Get patient audit history

Query Parameters:

• search - Search by MRN, name, phone
• gender - Filter by gender (MALE/FEMALE)
• is_active - Filter active patients
• ordering - Sort by created_at, mrn, first_name_en

Example:

GET /api/v1/patients/?search=john&gender=MALE&ordering=-created_at

Clinics

GET    /api/v1/clinics/                     - List all clinics
GET    /api/v1/clinics/{id}/                - Get clinic details

Query Parameters:

• specialty - Filter by specialty (MEDICAL, NURSING, ABA, OT, SLP)
• is_active - Filter active clinics

Files & SubFiles

GET    /api/v1/files/                       - List patient files
GET    /api/v1/files/{id}/                  - Get file details
GET    /api/v1/files/{id}/subfiles/         - Get file's subfiles
GET    /api/v1/subfiles/                    - List subfiles
GET    /api/v1/subfiles/{id}/               - Get subfile details

Consents

GET    /api/v1/consents/                    - List consents
POST   /api/v1/consents/                    - Create consent
GET    /api/v1/consents/{id}/               - Get consent details
PATCH  /api/v1/consents/{id}/               - Update consent
DELETE /api/v1/consents/{id}/               - Delete consent
POST   /api/v1/consents/{id}/verify/        - Verify signature

Attachments

GET    /api/v1/attachments/                 - List attachments
POST   /api/v1/attachments/                 - Upload attachment
GET    /api/v1/attachments/{id}/            - Get attachment details
DELETE /api/v1/attachments/{id}/            - Delete attachment

Audit Logs

GET    /api/v1/audit-logs/                  - List audit logs
GET    /api/v1/audit-logs/{id}/             - Get audit log details

---

📅 Appointments Module

Appointments

GET    /api/v1/appointments/                - List appointments
POST   /api/v1/appointments/                - Book appointment
GET    /api/v1/appointments/{id}/           - Get appointment details
PATCH  /api/v1/appointments/{id}/           - Update appointment
DELETE /api/v1/appointments/{id}/           - Cancel appointment

Query Parameters:

• patient - Filter by patient ID
• clinic - Filter by clinic ID
• provider - Filter by provider ID
• status - Filter by status
• scheduled_date - Filter by date
• start_date & end_date - Date range filter
• search - Search by appointment number, patient MRN/name

Workflow Actions:

POST   /api/v1/appointments/{id}/confirm/   - Confirm appointment
POST   /api/v1/appointments/{id}/arrive/    - Mark patient arrived
POST   /api/v1/appointments/{id}/start/     - Start appointment
POST   /api/v1/appointments/{id}/complete/  - Complete appointment
POST   /api/v1/appointments/{id}/cancel/    - Cancel with reason
POST   /api/v1/appointments/{id}/reschedule/ - Reschedule appointment

Special Endpoints:

GET    /api/v1/appointments/today/          - Today's appointments
GET    /api/v1/appointments/upcoming/       - Upcoming appointments
GET    /api/v1/appointments/statistics/     - Appointment statistics

Example - Book Appointment:

POST /api/v1/appointments/
{
  "patient": "uuid-here",
  "clinic": "uuid-here",
  "provider": "uuid-here",
  "room": "uuid-here",
  "service_type": "CONSULTATION",
  "scheduled_date": "2025-10-15",
  "scheduled_time": "10:00:00",
  "duration": 30,
  "notes": "First visit"
}

Example - Confirm Appointment:

POST /api/v1/appointments/{id}/confirm/
{
  "method": "SMS"
}

Example - Cancel Appointment:

POST /api/v1/appointments/{id}/cancel/
{
  "cancel_reason": "Patient requested cancellation"
}

Providers

GET    /api/v1/providers/                   - List providers
GET    /api/v1/providers/{id}/              - Get provider details
GET    /api/v1/providers/{id}/availability/ - Check availability
GET    /api/v1/providers/{id}/appointments/ - Provider's appointments

Example - Check Availability:

GET /api/v1/providers/{id}/availability/?start_date=2025-10-15&end_date=2025-10-20

Rooms

GET    /api/v1/rooms/                       - List rooms
GET    /api/v1/rooms/{id}/                  - Get room details

Schedules

GET    /api/v1/schedules/                   - List schedules
POST   /api/v1/schedules/                   - Create schedule
GET    /api/v1/schedules/{id}/              - Get schedule details
PATCH  /api/v1/schedules/{id}/              - Update schedule
DELETE /api/v1/schedules/{id}/              - Delete schedule

---

💰 Finance Module

Invoices

GET    /api/v1/invoices/                    - List invoices
POST   /api/v1/invoices/                    - Create invoice
GET    /api/v1/invoices/{id}/               - Get invoice details
PATCH  /api/v1/invoices/{id}/               - Update invoice
DELETE /api/v1/invoices/{id}/               - Delete invoice

Query Parameters:

• patient - Filter by patient ID
• status - Filter by status (DRAFT, ISSUED, PAID, etc.)
• issue_date - Filter by issue date
• search - Search by invoice number, patient MRN/name

Workflow Actions:

POST   /api/v1/invoices/{id}/issue/         - Issue draft invoice
GET    /api/v1/invoices/{id}/payments/      - Get invoice payments
POST   /api/v1/invoices/{id}/mark_paid/     - Mark as fully paid

Special Endpoints:

GET    /api/v1/invoices/overdue/            - Get overdue invoices
GET    /api/v1/invoices/statistics/         - Invoice statistics

Example - Create Invoice:

POST /api/v1/invoices/
{
  "patient": "uuid-here",
  "appointment": "uuid-here",
  "issue_date": "2025-10-13",
  "due_date": "2025-10-20",
  "subtotal": "500.00",
  "tax": "75.00",
  "discount": "0.00",
  "line_items": [
    {
      "service": "uuid-here",
      "description": "Medical Consultation",
      "quantity": 1,
      "unit_price": "500.00"
    }
  ],
  "notes": "Payment due within 7 days"
}

Payments

GET    /api/v1/payments/                    - List payments
POST   /api/v1/payments/                    - Record payment
GET    /api/v1/payments/{id}/               - Get payment details
PATCH  /api/v1/payments/{id}/               - Update payment
DELETE /api/v1/payments/{id}/               - Delete payment

Workflow Actions:

POST   /api/v1/payments/{id}/process/       - Process pending payment
POST   /api/v1/payments/{id}/refund/        - Refund completed payment

Example - Record Payment:

POST /api/v1/payments/
{
  "invoice": "uuid-here",
  "payment_date": "2025-10-13",
  "amount": "575.00",
  "method": "CARD",
  "transaction_id": "TXN123456",
  "reference": "Card ending 1234"
}

Services

GET    /api/v1/services/                    - List services (read-only)
GET    /api/v1/services/{id}/               - Get service details

Packages

GET    /api/v1/packages/                    - List packages (read-only)
GET    /api/v1/packages/{id}/               - Get package details

Package Purchases

GET    /api/v1/package-purchases/           - List package purchases
POST   /api/v1/package-purchases/           - Purchase package
GET    /api/v1/package-purchases/{id}/      - Get purchase details
PATCH  /api/v1/package-purchases/{id}/      - Update purchase
POST   /api/v1/package-purchases/{id}/use_session/ - Use one session

Payers

GET    /api/v1/payers/                      - List payers
POST   /api/v1/payers/                      - Create payer
GET    /api/v1/payers/{id}/                 - Get payer details
PATCH  /api/v1/payers/{id}/                 - Update payer
DELETE /api/v1/payers/{id}/                 - Delete payer

---

🔄 Referrals Module

Referrals

GET    /api/v1/referrals/                   - List referrals
POST   /api/v1/referrals/                   - Create referral
GET    /api/v1/referrals/{id}/              - Get referral details
PATCH  /api/v1/referrals/{id}/              - Update referral
DELETE /api/v1/referrals/{id}/              - Delete referral

Query Parameters:

• patient - Filter by patient ID
• from_clinic - Filter by source clinic
• to_clinic - Filter by destination clinic
• status - Filter by status (PENDING, ACCEPTED, COMPLETED, REJECTED)
• urgency - Filter by urgency (ROUTINE, URGENT, EMERGENCY)
• is_internal - Filter internal/external referrals

Workflow Actions:

POST   /api/v1/referrals/{id}/accept/       - Accept referral
POST   /api/v1/referrals/{id}/reject/       - Reject referral
POST   /api/v1/referrals/{id}/complete/     - Complete referral

Special Endpoints:

GET    /api/v1/referrals/sent/              - Sent referrals
GET    /api/v1/referrals/received/          - Received referrals
GET    /api/v1/referrals/pending/           - Pending referrals
GET    /api/v1/referrals/urgent/            - Urgent referrals
GET    /api/v1/referrals/statistics/        - Referral statistics
GET    /api/v1/referrals/workflow/          - Workflow statistics

Example - Create Referral:

POST /api/v1/referrals/
{
  "patient": "uuid-here",
  "from_clinic": "uuid-here",
  "to_clinic": "uuid-here",
  "from_provider": "uuid-here",
  "to_provider": "uuid-here",
  "reason": "Patient requires ABA assessment for behavioral concerns",
  "clinical_summary": "3-year-old with speech delay and repetitive behaviors",
  "urgency": "ROUTINE",
  "notes": "Parent prefers morning appointments"
}

Example - Accept Referral:

POST /api/v1/referrals/{id}/accept/
{
  "response_notes": "Referral accepted. Will schedule initial assessment within 2 weeks."
}

Referral Auto Rules

GET    /api/v1/referral-rules/              - List auto-referral rules
POST   /api/v1/referral-rules/              - Create rule
GET    /api/v1/referral-rules/{id}/         - Get rule details
PATCH  /api/v1/referral-rules/{id}/         - Update rule
DELETE /api/v1/referral-rules/{id}/         - Delete rule

---

Response Formats

Success Response

{
  "id": "uuid-here",
  "field1": "value1",
  "field2": "value2",
  ...
}

List Response

{
  "count": 100,
  "next": "http://localhost:8000/api/v1/patients/?page=2",
  "previous": null,
  "results": [
    {...},
    {...}
  ]
}

Error Response

{
  "error": "Error message here"
}

Validation Error Response

{
  "field_name": [
    "Error message for this field"
  ]
}

---

Common Query Parameters

Pagination

• page - Page number (default: 1)
• page_size - Items per page (default: varies by endpoint)

Filtering

• Use field names as query parameters
• Example: ?status=PENDING&urgency=URGENT

Search

• search - Full-text search across specified fields
• Example: ?search=john

Ordering

• ordering - Sort by field (prefix with - for descending)
• Example: ?ordering=-created_at

---

HTTP Status Codes

• 200 OK - Successful GET, PATCH, PUT
• 201 Created - Successful POST
• 204 No Content - Successful DELETE
• 400 Bad Request - Validation error
• 401 Unauthorized - Authentication required
• 403 Forbidden - Permission denied
• 404 Not Found - Resource not found
• 500 Internal Server Error - Server error

---

Rate Limiting

Not yet implemented. Will be added in future updates.

---

API Versioning

Current version: v1

Base URL includes version: /api/v1/

---

Testing the API

Using cURL

# List patients
curl -X GET http://localhost:8000/api/v1/patients/ \
  -H "Authorization: Token your-token-here"

# Create patient
curl -X POST http://localhost:8000/api/v1/patients/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token your-token-here" \
  -d '{
    "first_name_en": "John",
    "last_name_en": "Doe",
    "date_of_birth": "1990-01-01",
    "gender": "MALE",
    "phone": "+966501234567"
  }'

Using Python requests

import requests

# List patients
response = requests.get(
    'http://localhost:8000/api/v1/patients/',
    headers={'Authorization': 'Token your-token-here'}
)
patients = response.json()

# Create appointment
response = requests.post(
    'http://localhost:8000/api/v1/appointments/',
    headers={'Authorization': 'Token your-token-here'},
    json={
        'patient': 'uuid-here',
        'clinic': 'uuid-here',
        'provider': 'uuid-here',
        'scheduled_date': '2025-10-15',
        'scheduled_time': '10:00:00',
        'duration': 30
    }
)
appointment = response.json()

Using JavaScript fetch

// List appointments
fetch('http://localhost:8000/api/v1/appointments/', {
  headers: {
    'Authorization': 'Token your-token-here'
  }
})
.then(response => response.json())
.then(data => console.log(data));

// Create referral
fetch('http://localhost:8000/api/v1/referrals/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Token your-token-here'
  },
  body: JSON.stringify({
    patient: 'uuid-here',
    from_clinic: 'uuid-here',
    to_clinic: 'uuid-here',
    reason: 'Requires assessment',
    urgency: 'ROUTINE'
  })
})
.then(response => response.json())
.then(data => console.log(data));

---

Future Enhancements

1. Token Authentication - For mobile apps
2. Swagger/OpenAPI UI - Interactive API documentation
3. Rate Limiting - Prevent API abuse
4. Webhooks - Real-time notifications
5. Batch Operations - Bulk create/update
6. GraphQL Support - Alternative to REST
7. API Analytics - Usage tracking and monitoring

---

Support

For API support, contact: api@tenhal.com

Last Updated: October 13, 2025 API Version: v1.0.0