API Endpoints¶

All 14 Implemented Webhook Endpoints

Base URL¶

Environment	URL
Production	`https://api.vitaravox.ca:9443`
Development	`https://api-dev.vitaravox.ca:9443`

Authentication¶

All endpoints require authentication via API key header:

X-API-Key: <your-api-key>

Vapi webhooks are verified using HMAC signature:

X-Vapi-Signature: <hmac-sha256-signature>

Health & Status¶

GET /health¶

Health check endpoint. No authentication required.

Response:

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

Patient Lookup¶

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

Search patient by phone number (caller ID).

Request:

{
  "phone": "+16045551234"
}

Response (Found):

{
  "success": true,
  "patient": {
    "demographicNo": 12345,
    "firstName": "John",
    "lastName": "Smith",
    "phone": "604-555-1234"
  }
}

Response (Not Found):

{
  "success": true,
  "patient": null
}

POST /api/vapi/search-patient¶

Search patient by name.

Request:

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

Response:

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

POST /api/vapi/get-patient¶

Get full patient details by demographic number.

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.smith@email.com",
    "address": {
      "street": "123 Main St",
      "city": "Vancouver",
      "province": "BC",
      "postalCode": "V6A 1A1"
    }
  }
}

Clinic Information¶

POST /api/vapi/get-clinic-info¶

Get clinic configuration including registration status.

Request:

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

Response:

href="#__codelineno-11-1">{ "success": true, "clinic": { "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11", "name": "Downtown Medical Clinic", "phone": "604-555-0100", "address": "456 Health Ave, Vancouver, BC V6B 2B2", "accepting_new_patients": true, "waitlist_enabled": true, "hours": { "monday": { "open": "09:00", "close": "17:00" }, "tuesday": { "open": "09:00", "close": "17:00" }, "wednesday": { "open": "09:00", "close": "17:00" }, "thursday": { "open": "09:00", "close": "17:00" }, "friday": { "open": "09:00", "close": "17:00" }, "saturday": { "closed": true }, "sunday": { "closed": true } } } }

POST /api/vapi/get-providers¶

Get list of providers for a clinic.

Request:

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

Response:

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

Appointment Management¶

POST /api/vapi/find-earliest-appointment¶

Find the earliest available appointment slot.

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"
    }
  }
}

POST /api/vapi/check-appointments¶

Check available appointments or patient's existing 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 (Available):

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

POST /api/vapi/create-appointment¶

Book a new appointment.

Request:

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

Response:

{
  "success": true,
  "appointment": {
    "appointmentNo": 99001,
    "demographicNo": 12345,
    "providerNo": "100001",
    "date": "2026-01-14",
    "startTime": "09:30",
    "duration": 15,
    "status": "confirmed"
  }
}

POST /api/vapi/update-appointment¶

Reschedule an existing appointment.

Request:

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

Response:

{
  "success": true,
  "appointment": {
    "appointmentNo": 99001,
    "date": "2026-01-15",
    "startTime": "14:00",
    "status": "rescheduled"
  }
}

POST /api/vapi/cancel-appointment¶

Cancel an appointment.

Request:

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

Response:

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

Registration & Waitlist¶

POST /api/vapi/register-new-patient¶

Register a new patient in OSCAR EMR.

Request:

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

Response:

{
  "success": true,
  "patient": {
    "demographicNo": 12346,
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "message": "Patient registered successfully"
}

POST /api/vapi/add-to-waitlist¶

Add patient to new patient waitlist.

Request:

{
  "clinicId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "firstName": "Jane",
  "lastName": "Doe",
  "phone": "604-555-9876",
  "email": "jane.doe@email.com",
  "notes": "Interested in family medicine"
}

Response:

{
  "success": true,
  "waitlistId": "w-12345",
  "position": 15,
  "message": "Added to waitlist"
}

Call Management¶

POST /api/vapi/transfer-call¶

Transfer call to clinic staff.

Request:

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

Response:

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

POST /api/vapi/log-call¶

Log call metadata for analytics.

Request:

{
  "clinicId": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "vapiCallId": "call_abc123xyz",
  "callerPhone": "+16045551234",
  "demographicId": 12345,
  "language": "en",
  "intent": "book",
  "outcome": "booked",
  "appointmentId": 99001,
  "durationSeconds": 127,
  "transferredToStaff": false
}

Response:

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

Error Responses¶

All endpoints return consistent error format:

{
  "success": false,
  "error": {
    "code": "PATIENT_NOT_FOUND",
    "message": "No patient found with the provided criteria"
  }
}

Error Codes¶

Code	HTTP Status	Description
`PATIENT_NOT_FOUND`	404	Patient not found in EMR
`APPOINTMENT_NOT_FOUND`	404	Appointment not found
`NO_AVAILABILITY`	404	No appointments available
`INVALID_REQUEST`	400	Invalid request parameters
`OSCAR_UNAVAILABLE`	503	OSCAR EMR unreachable
`UNAUTHORIZED`	401	Invalid or missing API key
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Internal server error

Rate Limits¶

Endpoint	Limit	Burst
General API	100/min	20
Booking (`create-appointment`)	20/min	5
Health check	Unlimited	-

Admin API (v1.5.0+)¶

The Admin API provides endpoints for clinic and user management. All admin endpoints require JWT authentication.

Authentication¶

Authorization: Bearer <jwt-token>

Response Format¶

All admin endpoints return a consistent format:

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

Auth Endpoints¶

Endpoint	Method	Description
`/api/auth/login`	POST	User login, returns JWT tokens
`/api/auth/logout`	POST	User logout
`/api/auth/refresh`	POST	Refresh access token
`/api/auth/change-password`	POST	Change own password
`/api/auth/me`	GET	Get current user info

Admin - Clinics (Vitara Admin only)¶

Endpoint	Method	Description
`/api/admin/clinics`	GET	List clinics (paginated)
`/api/admin/clinics/stats`	GET	Clinic statistics
`/api/admin/clinics`	POST	Create clinic
`/api/admin/clinics/:id`	GET	Get clinic details
`/api/admin/clinics/:id`	PUT	Update clinic
`/api/admin/clinics/:id`	DELETE	Delete clinic
`/api/admin/clinics/:id/emr-config`	PUT	Update EMR config
`/api/admin/clinics/:id/go-live`	POST	Set EMR live status

Admin - Users (Vitara Admin only)¶

Endpoint	Method	Description
`/api/admin/users`	GET	List users (paginated)
`/api/admin/users`	POST	Create user
`/api/admin/users/:id`	GET	Get user details
`/api/admin/users/:id`	PUT	Update user
`/api/admin/users/:id`	DELETE	Delete user
`/api/admin/users/:id/reset-password`	POST	Reset password
`/api/admin/users/:id/unlock`	POST	Unlock account

Admin - Audit Logs (Vitara Admin only)¶

Endpoint	Method	Description
`/api/admin/audit-logs`	GET	List audit logs (paginated)
`/api/admin/audit-logs/summary`	GET	Activity summary

Clinic Manager - Self-Service¶

Endpoint	Method	Description
`/api/clinic/me`	GET	Get own clinic
`/api/clinic/preferences`	PUT	Update preferences
`/api/clinic/request-go-live`	POST	Request go-live

API Endpoints¶

Base URL¶

Authentication¶

Health & Status¶

GET /health¶

Patient Lookup¶

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

POST /api/vapi/search-patient¶

POST /api/vapi/get-patient¶

Clinic Information¶

POST /api/vapi/get-clinic-info¶

POST /api/vapi/get-providers¶

Appointment Management¶

POST /api/vapi/find-earliest-appointment¶

POST /api/vapi/check-appointments¶

POST /api/vapi/create-appointment¶

POST /api/vapi/update-appointment¶

POST /api/vapi/cancel-appointment¶

Registration & Waitlist¶

POST /api/vapi/register-new-patient¶

POST /api/vapi/add-to-waitlist¶

Call Management¶

POST /api/vapi/transfer-call¶

POST /api/vapi/log-call¶

Error Responses¶

Error Codes¶

Rate Limits¶

Admin API (v1.5.0+)¶

Authentication¶

Response Format¶

Auth Endpoints¶

Admin - Clinics (Vitara Admin only)¶

Admin - Users (Vitara Admin only)¶

Admin - Audit Logs (Vitara Admin only)¶

Clinic Manager - Self-Service¶

Next Steps¶