Skip to main content

PracSuite

Audience: Sales, support, engineering · Where in app: Settings → Integrations → Calendars & booking → PracSuite card ("Clinic Calendar") · Plan availability: All plans; the card shows Coming soon and a disabled Connect PracSuite until PRACSUITE_VENDOR_KEY is set

PracSuite (Smartsoft) is allied-health practice-management software. The integration (backend 1ca9a6548, ms-comm 6298093, ms-ai 4a5f3152c, frontend 2d73555a, 2026-11-03) is a deliberate copy of Semble: the clinic ticks appointment types, locations and practitioners, every combination is a "calendar", and the widget and AI agents book through SchedulingService. It is kept as its own code so the two never change each other.

Not live-verified

services/pracsuite/endpoints.js was verified against the public docs for availability, reserve, appointment and patient paths only. The business / practitioner / appointment-type list paths, patient filter fields, patient-create body and business timezone location are marked UNVERIFIED — no vendor key or sandbox existed when it shipped. Expect fixes there on the first live clinic.

How it works​

Two keys​

  • Our vendor key (x-api-key, env PRACSUITE_VENDOR_KEY), issued by PracSuite to approved developers. Without it PracSuiteService.configured is false: /pracsuite/status returns available: false (card shows Coming soon), connect answers 503, and PracSuiteSyncJob does nothing.
  • Each clinic's subscriber key, pasted on the card, validated by listing the clinic's businesses, stored in the credential vault (provider: 'pracsuite'), never returned.

Rate limit is per vendor key (5 req/s across every clinic), so one shared GhlRateLimiter bucket at 4/s. A daily quota (50,000) is also shared by all clinics, which is why the sync is bounded (below). An auth error on a stored key flips pracsuite.connection_status: 'expired' (card: Reconnect needed, ladder stops offering PracSuite).

Data (companies.pracsuite, strict subdoc)​

connected_at, practice_name, practice_timezone, locations[] {id,name} (PracSuite businesses), appointment_types[] {id,name,duration}, clinicians[] {id,name} (practitioners, named to match Semble's shape), enabled, connection_status (ok|error|expired), connection_error, last_verified_at, last_synced_at. Bookable = isPracSuiteBookable (services/pracsuite/choices.js): enabled + ≥1 of each + not expired. Calendar id <typeId>~<businessId>~<practitionerId|any>; "any" appears when more than one practitioner is ticked.

Session bookings: booking_type: 'pracsuite', pracsuite_appointment_id (string; PracSuite ids are integers). Only ids are kept — no patient record on our side.

Routes (routes/pracsuiteRoutes.js)​

RouteAuthPurpose
POST /pracsuite/connect, /options, /settings, /status, /rotate-key, /disconnect, /backfillpassport (web owner, or agency user with body.company_id in their agency)Card + modal. settings re-checks ids against PracSuite and enables booking; rotate-key refuses a key whose businesses don't contain the ticked ids; backfill (no UI) re-checks our bookings from 30 days back to 90 ahead
GET /pracsuite/:company_id/booking-calendarspublicWidget choice list (empty = one choice, skip the picker)
POST /pracsuite/availability, /pracsuite/bookpublic, forcePracSuiteCalendarSchedulingController handlers with calendar_type pinned to pracsuite, same reason as Semble (no BACKEND_API_KEY dependency). Meetings / reschedule / cancel stay on keyed /scheduling/*

Booking (scheduling/adapters/PracSuiteAdapter.js)​

  • Times: PracSuite app_time is clinic wall-clock with no offset, converted with practice_timezone (business timezone) else the company's. The card warns when the zone came from the account, not PracSuite (timezone_from_pracsuite: false).
  • Availability: available_appointments answers ≤ 7 days and no past dates, so a request is split into ≤ 4 calls (28-day max look-ahead). "Any" merges the ticked practitioners' slots.
  • Book: email or phone required. findOrCreatePatient = exact email, then phone tail, else create with name/email/mobile. A retry after a lost success returns the patient's existing appointment at that start (already_booked). Conflict → SLOT_TAKEN; auth → AUTH_EXPIRED. No notes/comments are sent (not in the documented body).
  • Cancel posts /appointment/{id}/cancel with {} — recorded in the patient's attendance history.
  • Ladder rung: after Semble, before ServiceM8.

Sync back (PracSuiteSyncJob)​

PracSuite has no webhooks. Every PRACSUITE_SYNC_INTERVAL_MINUTES (30) on the schedular, for each enabled non-expired company, syncCompany re-reads our upcoming PracSuite bookings one by one (next 30 days, ≤ 200 per company per run) and applies cancels/moves (> 1 min) to bookings[], the meetings mirror and notifications. Per-company errors are isolated.

Widget, ms-comm, ms-ai​

  • Widget reuses the Semble choice picker for bookingType === 'pracsuite' and fetches choices from /pracsuite/:company_id/booking-calendars.
  • ms-comm: SchedulingClientHelper.isPracSuiteBookingEnabled rung, routeFor sends availability/book to the public /pracsuite/*, MessageController.getPracSuiteAvailableSlots + _pracsuiteSlotsFailed.
  • ms-ai: PracSuite goes through backend scheduling like Semble; the choice prompt lists the three option lists and voice webhooks apply the same choice gate.

Configuration & environment​

Env (backend + schedular)DefaultNotes
PRACSUITE_VENDOR_KEY—Our vendor key; empty = integration shown as Coming soon
PRACSUITE_REQUEST_TIMEOUT_MS30000
PRACSUITE_RATE_LIMIT_MAX / _WINDOW_MS4 / 1000Shared across all clinics
PRACSUITE_SYNC_INTERVAL_MINUTES30Each run costs one call per upcoming booking against the shared daily quota

As of 2026-11-16 no flux environment sets PRACSUITE_VENDOR_KEY, so PracSuite is Coming soon everywhere. PracSuiteService is always loaded (global pracsuite); clinic keys live in the vault, so SECRET_ENCRYPTION_KEY must match between backend and schedular.

Technical implementation​

  • backend: services/PracSuiteService.js, services/pracsuite/{PracSuiteClient,endpoints,choices,errors}.js, scheduling/adapters/PracSuiteAdapter.js, controllers/PracSuiteController.js, middlewares/forcePracSuiteCalendar.js, jobs/PracSuiteSyncJob.js, configs/pracsuite.js. Specs: pracsuite-client, pracsuite-scheduling-adapter.
  • frontend: components/integrations/PracSuiteCard.vue, PracSuiteModal.vue (vee-validate + zod key form).