Integration architecture

ChiroHD Integration: How MedReception AI Reads and Writes to ChiroHD

This is the technical reference for how the MedReception AI voice agent talks to ChiroHD. It covers the API surface, the browser automation fallback for screens ChiroHD does not expose programmatically, OAuth setup, the exact fields we read and write, per clinic configuration, and the security model that keeps PHI scoped to a single tenant.

Integration Spec, ChiroHD Edition

Typical Setup

12 to 15 min

OAuth grant, visit type mapping, first sandbox call

API Endpoints Used

4 core

Schedule, patients, appointments, care plans

Write Success Rate

99.4%

Appointments and demographics committed on first try

Auth Model

OAuth 2

Per tenant bearer tokens, refresh handled server side

Product context

What ChiroHD Actually Is, From an Integration Standpoint

ChiroHD is a chiropractic specific EHR and practice management platform popular with multi doctor offices in the United States. Unlike horizontal EHRs that bolt chiropractic on as a specialty mode, ChiroHD models the things chiropractors actually do, care plans with visit balances, personal injury and auto injury intake, technique notes, and recurring appointment series. That chiropractic native data model is what makes the integration valuable, and it is also what shapes the API surface we work with.

Who Uses ChiroHD

• United States chiropractic practices, single and multi location
• Concentrated in multi doctor clinics with 3 or more providers
• Practices with a meaningful personal injury and auto injury caseload
• Offices that sell care plans rather than visit by visit
• Mixed cash and insurance billing workflows

What Makes ChiroHD Different

• Native care plan object with remaining visit count
• First class personal injury and auto injury intake fields
• Provider preference and technique fields on the patient record
• Recurring series scheduling rather than ad hoc booking
• Visit type taxonomy specific to chiropractic care

Integration architecture

API First, With a Browser Automation Fallback

The MedReception AI integration with ChiroHD is API first. Where ChiroHD exposes a documented endpoint, we use it. Where the behavior we need lives only inside the web app, we run a headless browser session as the same office user and operate the UI with deterministic selectors. Every action, API or browser, is journaled and reconciled against the live schedule afterward.

ChiroHD API Layer

• OAuth 2 authorization code flow with per tenant client
• Bearer token in Authorization header, refresh handled server side
• Sandbox and production environments isolated by base URL
• Idempotency keys on all write requests
• Retry with exponential backoff on 429 and 5xx responses

Browser Automation Layer

• Headless Playwright session running on a per tenant ECS task
• Logs in as a dedicated reception level office user
• Two attempts per login then permanent halt, no silent retry storms
• Used for screens with no API equivalent, never to bypass auth
• Same write payloads as API, same audit log entries

Setup Sequence

• Practice owner grants OAuth consent for the tenant
• Refresh token sealed into per tenant secret store
• Office user credentials added for the browser fallback
• Visit type and care plan mappings loaded from clinic config
• First sandbox booking placed end to end before go live

Reconciliation

• Every write is followed by a read back to confirm
• Mismatches trigger an alert to the operations channel
• Daily schedule diff catches drift between our journal and ChiroHD
• Failed writes never silently degrade the caller experience
• All retries cap at two attempts then surface to a human

Read surface

What MedReception AI Reads From ChiroHD

Read access is scoped to what the voice agent needs to qualify callers, find appointment slots, and respect care plan rules. We do not pull the full clinical chart. Each read path is documented below with its source endpoint or screen.

Provider Schedule

• Available slots per provider per day
• Visit type duration and provider mapping
• Blocked time, lunch, and out of office windows
• Recurring series openings for care plan visits
• Refreshed on demand and cached for short windows only

Care Plan Visit Balances

• Remaining visit count on the active care plan
• Plan start and expected end date
• Plan provider and recommended cadence
• Used to enforce visit caps when booking
• Surfaced to the caller so they know where they stand

Patient Demographics

• Name, date of birth, primary phone
• Preferred provider and technique
• Active status and any do not contact flag
• Pulled only after identity is verified on the call
• Never read for callers who have not authenticated

Personal Injury and Auto Injury Flags

• Active personal injury or auto injury case marker
• Attorney and adjuster reference fields if present
• Date of injury and case status
• Used to route the call into the personal injury intake flow
• See the chirohd auto injury workflow page for the full flow

Write surface

What MedReception AI Writes Into ChiroHD

Writes are deliberately narrow. The voice agent commits the things a front desk receptionist would commit, appointments, demographic updates, and personal injury intake fields. Anything that touches clinical data stays with the provider.

Appointments With Visit Type

• New patient consult, re exam, regular adjustment, therapy
• Visit type chosen from the clinic specific mapping
• Provider selected from caller preference and availability
• Duration inherited from the visit type definition
• Confirmation read back to caller before commit

Patient Demographics Updates

• Phone number, address, and preferred contact channel
• Spelled back to the caller before write
• Audit entry attributes the change to the AI agent user
• Never overwrites a field with an empty value
• Conflicts surface to the office for review, not silent overwrite

Personal Injury Intake Fields

• Date of injury, mechanism of injury, body regions affected
• Attorney name, firm, phone, and email if provided
• Insurance adjuster and claim number
• Police report number when caller has it
• Flags the chart for the provider to review on first visit

What We Never Write

• Clinical SOAP notes or assessment plans
• Diagnosis codes or treatment recommendations
• Care plan creation or visit count changes
• Billing posts or insurance claim submissions
• Anything outside the front desk scope of the AI agent

Per clinic configuration

How We Configure Each ChiroHD Clinic

No two ChiroHD offices use the platform the same way. Visit type names, care plan templates, and provider conventions all vary. Configuration lives in a per tenant record so the integration adapts without code changes.

Visit Type Mapping

• Office specific visit type names map to canonical categories
• Each mapping pins duration and default provider scope
• New patient versus established patient handled per visit type
• Updated through the tenant config without redeploy

Care Plan Template Recognition

• Clinic specific plan names recognized at read time
• Visit cadence rules applied when offering slots
• Remaining visit count gates which plan visits can be booked
• Plan expiration handled gracefully on the call

Provider Preferences

• Technique preferences logged per provider
• New patient acceptance per provider
• Personal injury caseload routing
• Languages spoken for caller matching

Security and audit

PHI Stays Where It Belongs

Per Tenant Tokens

Each clinic gets its own OAuth client and refresh token, sealed in a per tenant secret. There is no shared service account across clinics, so a credential rotation at one office never touches another.

Tenant isolation enforced at the secret level

Audit Log Retention

Every read and write is journaled with the caller identifier, the agent action, the ChiroHD endpoint or screen, and the response. Logs are retained per the practice business associate agreement and exportable on request.

Full read and write audit trail, exportable per BAA

PHI Minimization

The voice agent reads only fields it needs to complete the call. Clinical notes, lab results, and billing detail are out of scope and never requested. What is read is held in memory for the duration of the call and not persisted beyond the journal.

Read scope minimized, no clinical chart access

Consumer overview

Looking For the Plain English Version?

The ChiroHD hub explains the integration in practice owner terms, what callers experience, what the front desk sees, and what changes on day one.

ChiroHD Hub →

Workflow detail

See the AI Receptionist Workflow for ChiroHD

The AI receptionist for ChiroHD page walks the actual call flow, from greeting to commit, with the ChiroHD specific decision points called out.

AI Receptionist for ChiroHD →

Related resources