Quick Reference¶

Last Updated: 2026-03-09 | Codes, values, and cheat sheets

Appointment Type Codes¶

Source: booking-en.md:118-124

Code	Duration	Use Case
`B`	15 min	Checkup, general, not sure, prescription refill
`2`	30 min	Follow-up, check results
`3`	45 min	Pain/illness, sick visit, referral, specialist
`P`	15 min	Phone/virtual consultation

Mapping from Patient Speech¶

Patient Says (EN)	Patient Says (ZH)	appointmentType	visitReason
"checkup", "general", "physical", "not sure"	"体检", "普通检查", "不确定"	`B`	`checkup`
"follow-up", "results", "check results"	"复查", "看结果"	`2`	`follow_up`
"pain", "illness", "specific complaint"	"不舒服", "疼痛", "生病"	`3`	`sick_visit`
"prescription refill", "medication"	"配药", "续药"	`P`	`checkup`
"referral", "specialist"	"转诊", "专科"	`3`	`consultation`

Default: B / checkup if unclear after one clarification attempt.

Call Outcomes¶

Outcome	Description
`booked`	Appointment created
`rescheduled`	Appointment moved
`cancelled`	Appointment cancelled
`registered`	New patient registered
`waitlisted`	Added to waitlist
`transferred`	Transferred to staff
`no_action`	No action taken (caller hung up, error, or incomplete)

Call Intents¶

Intent	Description
`book`	Book new appointment
`reschedule`	Change existing appointment
`cancel`	Cancel appointment
`register`	New patient registration
`inquiry`	Clinic information request
`other`	Other/unclear intent

Transfer Reasons¶

Reason	Triggers
`medical_question`	Symptom, medication, test result
`billing`	Payment, insurance, cost
`frustrated`	After 2 failed attempts
`registration_error`	Registration failed
`patient_request`	"Let me speak to someone"

Value	Meaning	Source
`true` (default)	Patient consented or did not object (opt-out model)	Voice agent omits or passes `smsConsent: true`
`false`	Patient explicitly declined texts	Voice agent passes `smsConsent: false`

SMS Actions¶

Action	Template	Trigger
`booking_confirmation`	"Your appointment is confirmed..."	`create_appointment` succeeds
`reschedule_confirmation`	"Your appointment has been rescheduled..."	`update_appointment` succeeds
`cancellation_confirmation`	"Your appointment has been cancelled..."	`cancel_appointment` succeeds

All templates exist in EN and ZH (6 total). Custom templates configurable per-clinic via ClinicConfig.smsTemplates JSON.

SMS Guard Chain (5 checks, all must pass)¶

#	Check	Fails When
1	`TELNYX_API_KEY` set	Telnyx not configured
2	`smsSenderNumber` set	Clinic has no SMS number
3	`smsConsent ≠ false`	Patient explicitly declined
4	Patient phone valid	No E.164 phone on file
5	`smsEnabled ≠ false`	Clinic disabled SMS

See: SMS Integration

Language Codes¶

Code	Language	v2.3.0 STT	v2.3.0 TTS	v3.0 STT	v3.0 TTS
`en`	English	AssemblyAI Universal	ElevenLabs multilingual_v2	Deepgram nova-2 `en`	ElevenLabs multilingual_v2
`zh`	Mandarin Chinese	AssemblyAI Universal	ElevenLabs multilingual_v2	Deepgram nova-2 `zh`	Azure `zh-CN-XiaoxiaoNeural`

Day of Week¶

Value	Day
0	Sunday
1	Monday
2	Tuesday
3	Wednesday
4	Thursday
5	Friday
6	Saturday

Waitlist Status¶

Status	Description
`pending`	Awaiting contact
`contacted`	Staff reached out
`registered`	Now a patient
`declined`	Removed from list

Provider Status¶

Status	Description
`active`	Accepting appointments
`inactive`	Not currently practicing
`on_leave`	Temporarily unavailable

User Roles¶

Role	Access
`vitara_admin`	Platform administrator - all clinics, all settings
`clinic_manager`	Single clinic - own clinic settings, preferences

Ticket Status¶

Status	Description
`open`	New ticket
`in_progress`	Being worked on
`waiting`	Awaiting response
`resolved`	Issue resolved
`closed`	Ticket closed

Ticket Priority¶

Priority	Description
`low`	Non-urgent
`medium`	Normal priority
`high`	Important
`urgent`	Immediate attention needed

Clinic Status¶

Status	Description
`active`	Clinic is live
`inactive`	Clinic deactivated
`pending`	Awaiting activation

Onboarding Steps (v4.0.0)¶

Step	Name	Gate
1	Clinic Details	`clinicInfoDone`
2	EMR Connection	`emrConnected`
3	Business Hours	`hoursDone`
4	Validation	6 integration checks (2 required)

Pre-Launch Checks (10 total — 7 blocking + 3 informational)¶

#	Check ID	Blocking?
1	`clinic_info`	Yes
2	`business_hours`	Yes
3	`active_providers`	Yes
4	`emr_connection`	Yes
5	`vapi_assigned`	Yes
6	`privacy_officer`	Yes
7	`credentials_encrypted`	Yes
8	`test_call`	No (recommended)
9	`oscar_config_synced`	No (informational — within 7 days)
10	`schedule_data_flow`	No (informational — adapter returns slots)

EMR Types¶

Type	Status	Integration
`oscar`	Supported	SOAP/WS-Security or REST Bridge
`telus`	Coming soon	TELUS PS Suite / Med Access / Wolf
`accuro`	Coming soon	QHR Technologies
`other`	Coming soon	Custom integration

Clinic Status Flow¶

pending → active (via admin activation)

Fax Status Codes¶

Status	Description
`pending`	Fax received, not yet processed
`processing`	AI extraction in progress
`extracted`	AI extraction complete, matching not yet run
`matched`	Patient matched in OSCAR (confidence >= 0.85)
`review_needed`	No confident match -- MOA review required
`verified`	MOA confirmed or corrected the match
`error`	Processing failed (see `errorMessage`)

Fax Document Types (AI-detected)¶

Type	Description
`referral_letter`	Referral from another provider
`lab_result`	Laboratory results
`specialist_report`	Specialist consultation report
`prescription_renewal`	Prescription renewal request
`insurance_form`	Insurance or pre-authorization form
`imaging_report`	X-ray, MRI, CT report
`discharge_summary`	Hospital discharge summary
`other`	Unclassified document

Fax Match Methods¶

Method	Confidence	Description
`phn_exact`	1.0	PHN matched exactly in OSCAR
`phn_search`	0.85	PHN found via search (partial)
`name_dob`	0.75-0.95	Name + date of birth match
`name_only`	0.50-0.75	Name match only (no DOB/PHN)
`manual_correction`	1.0	MOA manually corrected the match

Fax AI Providers¶

`FAX_AI_PROVIDER`	Model	Notes
`anthropic`	Claude (configurable via `FAX_ANTHROPIC_MODEL`, default: `claude-sonnet-4-6`)	Default, recommended
`openai`	GPT-4o-mini	Fallback
`google`	Gemini 2.0 Flash	Fallback

Fax Accepted File Types¶

MIME Type	Extensions	Processing
`application/pdf`	`.pdf`	pdftoppm → PNG pages
`image/png`	`.png`	Direct to AI vision
`image/jpeg`	`.jpg`, `.jpeg`	Direct to AI vision
`image/tiff`	`.tiff`, `.tif`	sharp → PNG pages

Max file size: 10MB. Max pages sent to AI: 5.

HTTP Status Codes¶

Code	Meaning
200	Success
400	Bad request (invalid params)
401	Unauthorized (invalid API key)
404	Not found
429	Rate limited
500	Internal server error
503	Service unavailable

Error Codes¶

Code	Description
`PATIENT_NOT_FOUND`	Patient not in EMR
`APPOINTMENT_NOT_FOUND`	Appointment doesn't exist
`NO_AVAILABILITY`	No slots available
`INVALID_REQUEST`	Invalid parameters
`OSCAR_UNAVAILABLE`	EMR unreachable
`UNAUTHORIZED`	Invalid credentials
`RATE_LIMITED`	Too many requests
`INTERNAL_ERROR`	Server error

PM2 Commands¶

# Check all processes
pm2 status

# View logs
pm2 logs vitara-admin-api

# Last 100 lines of logs
pm2 logs vitara-admin-api --lines 100

# Restart server
pm2 restart vitara-admin-api

# Live monitoring
pm2 monit

# Process details
pm2 describe vitara-admin-api

# Enter database
psql -U vitara -d vitara_platform

# Backup database
pg_dump -U vitara vitara_platform > backup.sql

API Endpoints Summary¶

Patient¶

Endpoint	Purpose
`POST /api/vapi/search-patient-by-phone`	Find by phone
`POST /api/vapi/search-patient`	Find by name
`POST /api/vapi/get-patient`	Get details

Clinic¶

Endpoint	Purpose
`POST /api/vapi/get-clinic-info`	Clinic settings
`POST /api/vapi/get-providers`	Provider list

Appointments¶

Endpoint	Purpose
`POST /api/vapi/find-earliest-appointment`	Find slot
`POST /api/vapi/check-appointments`	List appointments
`POST /api/vapi/create-appointment`	Book
`POST /api/vapi/update-appointment`	Reschedule
`POST /api/vapi/cancel-appointment`	Cancel

Registration¶

Endpoint	Purpose
`POST /api/vapi/register-new-patient`	Register
`POST /api/vapi/add-to-waitlist`	Add to waitlist

Call¶

Endpoint	Purpose
`POST /api/vapi/transfer-call`	Transfer
`POST /api/vapi/log-call-metadata`	Log call metadata (v3.0)

SMS Configuration¶

Endpoint	Purpose
`GET /api/clinic/config/sms`	Get clinic SMS settings
`POST /api/clinic/config/sms`	Update SMS config (sender, templates, enabled)
`POST /api/clinic/config/sms/validate`	Validate SMS number via Telnyx

Health¶

Endpoint	Purpose
`GET /health`	Health check

Onboarding & Provisioning (v4.0.0+)¶

Endpoint	Purpose
`GET /api/clinic/onboarding`	Onboarding progress
`PUT /api/clinic/onboarding`	Update onboarding step flags
`GET /api/clinic/onboarding/validate`	Run pre-launch validation checks
`POST /api/clinic/onboarding/go-live`	Activate clinic (blocked if checks fail)
`POST /api/clinic/onboarding/complete`	Complete onboarding (notifies admin)
`POST /api/clinic/onboarding/test-slots`	Test schedule slot retrieval
`POST /api/clinic/onboarding/test-patient-search`	Test patient search
`GET /api/clinic/oscar-config`	OSCAR config (codes, types)
`POST /api/clinic/oscar-config/pull`	Pull config from OSCAR
`GET /api/admin/clinics/pending-activation`	Clinics awaiting activation
`GET /api/admin/clinics/:id/provisioning`	Provisioning status
`PUT /api/admin/clinics/:id/activate`	Activate clinic

Fax Intelligence API (v4.1.0)¶

Endpoint	Purpose
`POST /api/fax/upload`	Upload fax PDF/image for AI processing
`GET /api/fax/documents`	List fax documents (paginated, filterable by status)
`GET /api/fax/documents/:id`	Get fax detail with extraction + match data
`PUT /api/fax/documents/:id/verify`	Confirm or correct patient match
`POST /api/fax/polling/start`	Start inbox polling
`POST /api/fax/polling/stop`	Stop inbox polling
`GET /api/fax/polling/status`	Poller status + counts
`POST /api/fax/seed`	Seed fixture fax (demo)
`POST /api/fax/reset`	Reset mock inbox (demo)
`GET /api/fax/fixtures`	List available fixtures

Admin API (v1.5.0+)¶

Endpoint	Purpose
`POST /api/auth/login`	User login
`POST /api/auth/logout`	User logout
`POST /api/auth/refresh`	Refresh access token
`GET /api/auth/me`	Get current user
`GET /api/admin/clinics`	List clinics (paginated)
`POST /api/admin/clinics`	Create clinic
`GET /api/admin/clinics/:id`	Get clinic details
`PUT /api/admin/clinics/:id`	Update clinic
`GET /api/admin/users`	List users (paginated)
`POST /api/admin/users`	Create user
`GET /api/admin/audit-logs`	List audit logs

Rate Limits¶

Category	Limit	Scope
Auth endpoints (`/api/auth/*`)	5/min	Per IP
General API (`/api/*`)	100/min	Per IP
Webhooks (`/api/vapi`)	300/min	Per IP
Health (`/health`)	Unlimited	—

Environment Variables¶

# Required - Core
NODE_ENV=production              # Environment
DATABASE_URL=postgresql://...    # PostgreSQL connection
ENCRYPTION_KEY=                  # AES-256-GCM key (32-byte hex)

# Required - Auth
JWT_SECRET=                      # Access token signing key
JWT_REFRESH_SECRET=              # Refresh token signing key

# Required - Vapi
VAPI_API_KEY=                    # Vapi API key (server-side calls)
VAPI_WEBHOOK_SECRET=             # Vapi HMAC verification

# Optional - EMR
OSCAR_BRIDGE_URL=                # REST Bridge URL (dev/fallback only)
OSCAR_BRIDGE_API_KEY=            # REST Bridge API key
DEFAULT_EMR_TYPE=oscar-soap      # Adapter type

# Optional - Server
PORT=3002                        # Server port
CORS_ORIGIN=https://dev.vitaravox.ca
LOG_LEVEL=info                   # Pino log level
VITARA_DEBUG=false               # PHI-DEBUG mode (auto-expires 4h)

# Optional - Auth
JWT_EXPIRES_IN=1h                # Access token expiry
JWT_REFRESH_EXPIRES_IN=7d        # Refresh token expiry

# SMS (platform-level, per-clinic sender numbers in DB)
TELNYX_API_KEY=                  # Telnyx API v2 key
TELNYX_MESSAGING_PROFILE_ID=     # Telnyx messaging profile UUID

# GitOps (in vapi-gitops/.env.dev)
VAPI_TOKEN=                      # Vapi GitOps API token

# Fax Intelligence (v4.1.0)
ANTHROPIC_API_KEY=               # Claude API key (default provider)
OPENAI_API_KEY=                  # GPT-4o-mini fallback
GOOGLE_AI_API_KEY=               # Gemini 2.0 Flash fallback
FAX_AI_PROVIDER=anthropic        # anthropic | openai | google
FAX_ANTHROPIC_MODEL=claude-sonnet-4-20250514  # Anthropic model ID
FAX_PROVIDER=mock                # mock | srfax
FAX_POLL_INTERVAL_MS=60000       # Poller interval in ms
FAX_UPLOAD_DIR=uploads/fax       # Local upload directory

Production OSCAR credentials

Production OSCAR SOAP credentials (username, password, endpoint URL) are stored per-clinic in the database and encrypted with ENCRYPTION_KEY. They are not set via environment variables. The OSCAR_BRIDGE_URL / OSCAR_BRIDGE_API_KEY env vars are only used for the REST Bridge path (dev/fallback).

No TRANSFER_NUMBER env var

Transfer phone numbers are stored per-clinic in ClinicConfig.transferPhoneNumber.

Ports¶

Service	Port	Notes
Admin API (PM2)	3002	`vitara-admin-api` process
PostgreSQL	5432	Local, database: vitara_platform
NGINX HTTPS	443	Host-level, SSL termination
OSCAR SOAP	8443	OSCAR CXF endpoints
OSCAR Bridge	3000	Dev/fallback only

Paths¶

Path	Description
`/home/ubuntu/vitara-platform/`	Platform source
`/home/ubuntu/vitara-platform/admin-dashboard/server/`	Server source (TypeScript)
`/home/ubuntu/vitara-platform/vapi-gitops/`	Vapi GitOps config
`/etc/nginx/sites-enabled/`	NGINX configs
`/etc/letsencrypt/live/vitaravox.ca/`	SSL certificates
`/home/ubuntu/vitaravox-docs/`	Documentation site