API Reference¶

Complete endpoint documentation

Base Information¶

Item	Value
Base URL	`https://api.vitaravox.ca:9443`
Protocol	HTTPS (TLS 1.2+)
Format	JSON
Auth	API Key (X-API-Key header)

Authentication¶

Include API key in request header:

X-API-Key: your-api-key-here
Content-Type: application/json

Endpoints¶

Health Check¶

GET /health

No authentication required.

Response:

{
  "status": "healthy",
  "timestamp": "2026-01-12T15:30:00.000Z",
  "version": "1.1.0",
  "components": {
    "database": { "healthy": true },
    "oscar": { "healthy": true }
  }
}

Search Patient by Phone¶

POST /api/vapi/search-patient-by-phone

Request:

{
  "phone": "+16045551234"
}

Response:

{
  "success": true,
  "patient": {
    "demographicNo": 12345,
    "firstName": "John",
    "lastName": "Smith"
  }
}

Search Patient by Name¶

POST /api/vapi/search-patient

Request:

{
  "firstName": "John",
  "lastName": "Smith"
}

Response:

{
  "success": true,
  "patients": [
    {
      "demographicNo": 12345,
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "1985-03-15"
    }
  ]
}

Get Patient Details¶

POST /api/vapi/get-patient

Request:

{
  "demographicNo": 12345
}

Response:

{
  "success": true,
  "patient": {
    "demographicNo": 12345,
    "firstName": "John",
    "lastName": "Smith",
    "dateOfBirth": "1985-03-15",
    "sex": "M",
    "hin": "9876543210",
    "phone": "604-555-1234",
    "email": "john@email.com",
    "address": {
      "street": "123 Main St",
      "city": "Vancouver",
      "province": "BC",
      "postalCode": "V6A 1A1"
    }
  }
}

Get Clinic Info¶

POST /api/vapi/get-clinic-info

Request:

{
  "clinicId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
}

Response:

{
  "success": true,
  "clinic": {
    "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "name": "Downtown Medical",
    "phone": "604-555-0100",
    "address": "456 Health Ave",
    "accepting_new_patients": true,
    "waitlist_enabled": true,
    "hours": {
      "monday": { "open": "09:00", "close": "17:00" },
      "tuesday": { "open": "09:00", "close": "17:00" }
    }
  }
}

Get Providers¶

POST /api/vapi/get-providers

Request:

{
  "clinicId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"
}

Response:

{
  "success": true,
  "providers": [
    {
      "providerNo": "100001",
      "displayName": "Dr. Sarah Chen",
      "specialty": "Family Medicine"
    }
  ]
}

Find Earliest Appointment¶

POST /api/vapi/find-earliest-appointment

Request:

{
  "appointmentType": "B",
  "providerId": "any",
  "startDate": "2026-01-13"
}

Response:

{
  "success": true,
  "appointment": {
    "date": "2026-01-14",
    "time": "09:30",
    "duration": 15,
    "provider": {
      "providerNo": "100001",
      "displayName": "Dr. Sarah Chen"
    }
  }
}

Check Appointments¶

POST /api/vapi/check-appointments

Request (Find Available):

{
  "providerId": "100001",
  "startDate": "2026-01-13",
  "endDate": "2026-01-20",
  "findAvailable": true
}

Request (Patient's Appointments):

{
  "demographicNo": 12345,
  "findAvailable": false
}

Response:

{
  "success": true,
  "appointments": [
    {
      "date": "2026-01-14",
      "time": "09:30",
      "provider": { "displayName": "Dr. Chen" }
    }
  ]
}

Create Appointment¶

POST /api/vapi/create-appointment

Request:

{
  "demographicNo": 12345,
  "providerNo": "100001",
  "date": "2026-01-14",
  "startTime": "09:30",
  "duration": 15,
  "appointmentType": "B",
  "reason": "Prescription refill"
}

Response:

{
  "success": true,
  "appointment": {
    "appointmentNo": 99001,
    "status": "confirmed"
  }
}

Update Appointment¶

POST /api/vapi/update-appointment

Request:

{
  "appointmentNo": 99001,
  "newDate": "2026-01-15",
  "newStartTime": "14:00"
}

Response:

{
  "success": true,
  "appointment": {
    "appointmentNo": 99001,
    "status": "rescheduled"
  }
}

Cancel Appointment¶

POST /api/vapi/cancel-appointment

Request:

{
  "appointmentNo": 99001,
  "reason": "Patient requested"
}

Response:

{
  "success": true,
  "message": "Appointment cancelled"
}

Register New Patient¶

POST /api/vapi/register-new-patient

Request:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "dateOfBirth": "1990-05-20",
  "sex": "F",
  "hin": "9123456789",
  "phone": "604-555-9876",
  "address": {
    "street": "789 Oak St",
    "city": "Vancouver",
    "province": "BC",
    "postalCode": "V6C 3C3"
  }
}

Response:

{
  "success": true,
  "patient": {
    "demographicNo": 12346
  }
}

Add to Waitlist¶

POST /api/vapi/add-to-waitlist

Request:

{
  "clinicId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "604-555-9876"
}

Response:

{
  "success": true,
  "waitlistId": "w-12345",
  "position": 15
}

Transfer Call¶

POST /api/vapi/transfer-call

Request:

{
  "reason": "medical_question",
  "context": "Patient asking about medication"
}

Response:

{
  "success": true,
  "action": "transfer",
  "destination": "+16045550100"
}

Log Call¶

POST /api/vapi/log-call

Request:

{
  "clinicId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "vapiCallId": "call_abc123",
  "language": "en",
  "intent": "book",
  "outcome": "booked",
  "durationSeconds": 127
}

Response:

{
  "success": true,
  "logId": "log-67890"
}

Admin API¶

The Admin API endpoints for clinic and user management use JWT authentication and follow a standard response format. See Admin UI Guide for complete documentation.

Standard Admin Response Format¶

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 25,
    "totalPages": 3
  }
}

Admin Authentication¶

Authorization: Bearer <jwt-token>

Error Response Format¶

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Error Codes¶

Code	HTTP	Description
PATIENT_NOT_FOUND	404	Patient not in EMR
APPOINTMENT_NOT_FOUND	404	Appointment doesn't exist
NO_AVAILABILITY	404	No slots available
INVALID_REQUEST	400	Invalid parameters
OSCAR_UNAVAILABLE	503	EMR unreachable
UNAUTHORIZED	401	Invalid API key
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error