Healthcare HMS integration

Optional path for hospital management systems (or any custom platform) that already own doctors, slots, booking, and patient identity. Clinics that only need Google Calendar can ignore this page. Use the normal healthcare inbound wizard and choose Google Calendar + CRM - do not select HMS Custom API. Use your platform’s hospital / branch / doctor IDs everywhere below. Placeholders like YOUR_BRANCH_ID are not real values.

HMS platform checklist (end-to-end)

Any hospital / HMS vendor can follow this ordered list. Full request/response samples for each use_case are in Tenant webhook contract.

Phase 0 - Prerequisites

HMS owns patients, hospitals/branches, doctors, slots, and bookings (source of truth).
Ondial tenant can own inbound PSTN numbers via Public API purchase (when credits allow) or dashboard assign/purchase.
HMS exposes one public HTTPS webhook URL (e.g. https://api.your-hms.com/ondial).
Shared secret agreed (YOUR_SHARED_SECRET) for Authorization: Bearer ….
(API path) Ondial API key requested and approved (ond_live_…).

Phase 1 - Build the webhook (standard contract)

Expose one POST endpoint. Every body includes operation + use_case. Switch on use_case. Minimum for appointments (any scope):

#	use_case	operation	HMS must
1	`doctor_list`	`list`	Return doctors (`doctor_id`, `name`, `specialization?`)
2	`doctor_slots`	`list`	Return open slots (`slot_id`, `datetime`, `display_label`)
3	`book_appointment`	`write`	Create booking; return `{ "success": true, "booking_id" }`

Required for global scope only:

#	use_case	operation
4	`category_list`	`list`
5	`hospital_list`	`list`

Optional features:

#	use_case	operation	When
6	`patient_lookup`	`read`	Patient identify at call start
7	`lab_report`	`read`	Lab inquiry enabled on the agent
8	`prescriptions`	`read`	Prescription routing enabled on the agent

Example request your HMS receives:

{
  "operation": "list",
  "use_case": "doctor_slots",
  "doctor_id": "YOUR_DOCTOR_ID",
  "branch_id": "YOUR_BRANCH_ID",
  "max_slots": 3
}

Example success responses:

{
  "values": [
    {
      "doctor_id": "YOUR_DOCTOR_ID",
      "name": "Dr Example",
      "specialization": "Cardiology"
    }
  ]
}

{
  "values": [
    {
      "slot_id": "YOUR_SLOT_ID",
      "datetime": "2026-09-01T09:30:00+05:30",
      "display_label": "Mon 1 Sep, 9:30 AM"
    }
  ]
}

{
  "success": true,
  "booking_id": "YOUR_BOOKING_ID"
}

Rules:

HTTPS in production; respond within timeout (default 8000 ms).
Honor Bearer secret when configured.
Use stable IDs from your DB (branch_id / hospital_id / doctor_id / slot_id).
Hospital/doctor-scoped agents: Ondial may inject locked branch_id / doctor_id - accept them.
patient_lookup failure → soft fail (call continues). Slots/book failure → hard fail (do not fake success).

Phase 2 - Wire the agent in Ondial

Pick one scope per phone number:

Scope	HMS IDs to set on the agent	Sync doctors?
`global`	none	No (catalogs fetched live)
`hospital`	`branchId` = your hospital/org ID	Yes
`doctor`	`branchId` + `doctorId`	Yes (optional confirm)

Dashboard path: Inbound → Healthcare → Integration type HMS Custom API → Base URL + secret → Appointments ON → scope + your IDs → Save → Sync doctors → Activate. API path (HMS backend - recommended for SaaS):

GET /api/v1/credits - check balance before buy
GET /api/v1/numbers/available - browse pool inventory with per-number cost
POST /api/v1/numbers/purchase - buy when credits suffice (402 insufficient_credits if not)
GET /api/v1/numbers - confirm owned numbers
GET /api/v1/companies - pick companyId (scope companies:read; create via POST /companies if needed)
GET /api/v1/knowledge-bases/documents - pick fileIds (scope knowledge:read; upload via POST …/documents if needed)
GET /api/v1/voices?market=IN&language=hi-IN&tier=premium - pick voices[i].selectedVoice (copy as-is)
POST /api/v1/inbound-agents (scope + customApiBaseUrl + companyId + selectedKnowledgebases + selectedVoice + primaryLanguage; or omit voice for auto-default / use copyVoiceFromAgentId)
POST /api/v1/inbound-agents/{id}/sync-doctors (hospital/doctor only)
POST /api/v1/inbound-agents/{id}/generate-script
POST /api/v1/inbound-agents/{id}/activate with { "activate": true }

Create enables Appointments and hcBookingPath: custom_api automatically when scope + Custom API URL are set. If companyId is omitted, Ondial auto-picks the latest company. Create example (hospital):

{
  "phoneNumber": "+91xxxxxxxxxx",
  "category": "healthcare_reception",
  "appointmentScope": "hospital",
  "branchId": "YOUR_BRANCH_ID",
  "companyId": "YOUR_COMPANY_ID",
  "selectedKnowledgebases": ["YOUR_FILE_ID"],
  "primaryLanguage": "hi-IN",
  "selectedVoice": {
    "name": "Priya",
    "displayName": "Ishita",
    "gender": "Female",
    "language": { "code": "hi-IN", "name": "Hindi" },
    "tier": "premium",
    "accent": "Standard",
    "playbackSpeed": 0.9
  },
  "customApiBaseUrl": "https://YOUR_HMS_HOST/ondial",
  "customApiSecret": "YOUR_SHARED_SECRET",
  "slotsEnabled": true,
  "bookingEnabled": true,
  "doctorsSyncEnabled": true
}

Phase 3 - Runtime (live call)

Scope	Expected calls on your webhook
Global	catalogs → `doctor_slots` → `book_appointment`
Hospital	locked `branch_id`; `doctor_slots` → `book_appointment` (after sync)
Doctor	locked `branch_id` + `doctor_id`; `doctor_slots` → `book_appointment`

Phase 4 - Ongoing management

Task	How
Check credits / buy number	`GET /api/v1/credits` → `GET /api/v1/numbers/available` → `POST /api/v1/numbers/purchase`
Change scope / IDs / URL	Dashboard or `PATCH /api/v1/inbound-agents/{id}`
Delete agent (keep DID)	`DELETE /api/v1/inbound-agents/{id}`
Refresh doctor cache	`POST /api/v1/inbound-agents/{id}/sync-doctors` (hospital/doctor; global → `422 sync_not_allowed`)
Activate / deactivate	`POST /api/v1/inbound-agents/{id}/activate`
Dry-run lookup (no live call)	`POST /api/v1/inbound-agents/{id}/crm/lookup`
Stop the number	Deactivate the agent in Ondial

Phase 5 - Go-live verification

Webhook reachable over HTTPS with Bearer auth.
Sync doctors returns your real doctor list (hospital/doctor scopes).
Test call produces doctor_slots then book_appointment in HMS logs.
Booking ID exists in your HMS.
Google Calendar is not required on this path.

Architecture

The voice agent never calls your HMS directly. It calls Ondial mid-call APIs; Ondial POSTs to your HTTPS webhook.

When	Ondial endpoint	What Ondial POSTs to your webhook
Call start (if patient lookup on)	Internal validate hook	`operation: read`, `use_case: patient_lookup`
Categories / hospitals / doctors	`POST /api/inbound/crm`	`list` + `category_list` / `hospital_list` / `doctor_list`
Lab report (if enabled)	`POST /api/inbound/crm`	`read` + `lab_report`
Prescription (if enabled)	`POST /api/inbound/crm`	`read` + `prescriptions`
Slot search	`POST /api/inbound/slots`	`list` + `doctor_slots`
Book appointment	`POST /api/inbound/book`	`write` + `book_appointment`
Sync doctors (admin)	`POST /api/v1/inbound-agents/{id}/sync-doctors`	`list` + `doctor_list`

What you get

Scope (`appointmentScope`)	Config	What callers can book
`global`	No `branchId` / `doctorId`	Any hospital / specialty / doctor in your network
`hospital`	`branchId` = your hospital/org ID	Only doctors at that hospital
`doctor`	`branchId` + `doctorId` from your HMS	Only that doctor (goes straight to slots)

One Ondial phone number = one scope. Buy or assign a number, then attach the scope. Reuse the same webhook URL on many numbers. On a global number the voice agent supports both:

Hospital → category → doctor → slots → book
Category → doctor → hospital → slots → book

Setup in the dashboard

Own an Ondial number

Purchase via Public API (GET /credits → GET /numbers/available → POST /numbers/purchase) or in the dashboard.

Open inbound setup

Choose category Healthcare Reception. Features start off.

Pick integration type

Select HMS Custom API (not Google Calendar + CRM).

Connect your webhook

Enter your HTTPS Base URL and optional Bearer secret. Production must use https://.

Enable features and scope

Turn on Appointments. Choose scope: global, hospital (your branch/org ID), or doctor (your branch + doctor ID). Optionally enable lab report / prescription inquiry and patient lookup.

Save, sync, activate

Save the agent. For hospital/doctor scopes, click Sync doctors from HMS. Open Review & Launch and activate.

Day-to-day HMS backends can do the same via Public API without opening the dashboard after the first wire-up.

Setup via Public API (HMS admin)

Get an API key

Request API access. Use Authorization: Bearer ond_live_… from your HMS backend.

Own Ondial numbers

From your HMS backend: GET /api/v1/credits → GET /api/v1/numbers/available → POST /api/v1/numbers/purchase (pool inventory; credits debited). Or purchase in the dashboard. Then GET /api/v1/numbers to list owned DIDs.

Implement your webhook

Expose one HTTPS URL. Ondial POSTs { operation, use_case, ...fields }. See webhook contract.

Create an inbound agent

Optionally GET /api/v1/companies and GET /api/v1/knowledge-bases/documents to pick ids. Then POST /api/v1/inbound-agents with appointmentScope, Custom API URL, flags, and optionally companyId + selectedKnowledgebases: ["fileId", …]. Optional copyVoiceFromAgentId to copy voice/language from an existing agent. This sets Appointments ON and hcBookingPath: custom_api automatically. Agent starts inactive.

Sync doctors (hospital / doctor only)

POST /api/v1/inbound-agents/{id}/sync-doctors. Global numbers skip this - catalogs are fetched live during the call.

Generate script

POST /api/v1/inbound-agents/{id}/generate-script. Wait until inboundScriptStatus is ready (poll GET …/inbound-agents/{id}).

Activate

POST /api/v1/inbound-agents/{id}/activate with { "activate": true }.

Create examples

Global helpdesk number

{
  "phoneNumber": "+91xxxxxxxxxx",
  "category": "healthcare_reception",
  "name": "Network helpdesk",
  "appointmentScope": "global",
  "customApiBaseUrl": "https://YOUR_HMS_HOST/ondial",
  "customApiSecret": "YOUR_SHARED_SECRET",
  "slotsEnabled": true,
  "bookingEnabled": true,
  "validateHookEnabled": true
}

Hospital line

{
  "phoneNumber": "+91yyyyyyyyyy",
  "category": "healthcare_reception",
  "name": "Main hospital line",
  "appointmentScope": "hospital",
  "branchId": "YOUR_BRANCH_ID",
  "customApiBaseUrl": "https://YOUR_HMS_HOST/ondial",
  "customApiSecret": "YOUR_SHARED_SECRET",
  "slotsEnabled": true,
  "bookingEnabled": true,
  "doctorsSyncEnabled": true
}

Then sync doctors and activate.

HMS admin UX (your platform)

Hospital staff use your HMS admin UI only. Your backend calls Ondial with one tenant API key (ond_live_…). Never expose the API key to the browser.

Recommended screens

Screen	Ondial calls	Notes
Credits & numbers	`GET /api/v1/credits`, `GET /api/v1/numbers`, `GET /api/v1/numbers/available`, `POST /api/v1/numbers/purchase`	Disable Buy when `credits < cost`; show `402 insufficient_credits` from purchase
Voice agents list	`GET /api/v1/inbound-agents`	Show number, scope, status, branch/doctor IDs
Create / edit agent	`POST` or `PATCH /api/v1/inbound-agents`, then sync + activate	Scope picker: Global / Hospital / Doctor

Server module (HMS codebase)

Store in HMS env (server-side only):

ONDIAL_BASE_URL - e.g. https://dashboard.ondial.ai
ONDIAL_API_KEY - ond_live_… from Ondial API Access

All HMS UI requests go HMS browser → HMS API → Ondial Public API. Map HMS hospital/doctor records to branchId / doctorId on create.

Buy-number sequence

Purchase example

POST /api/v1/numbers/purchase
Authorization: Bearer ond_live_...
Content-Type: application/json

{ "phoneNumberId": "66f..." }

{
  "purchased": [{ "id": "66f...", "number": "+91xxxxxxxxxx", "cost": 7 }],
  "totalCost": 7,
  "creditsRemaining": 493
}

Create agent after purchase (all scopes)

Use phoneNumberId from purchase response or phoneNumber E.164 from GET /api/v1/numbers. Global - no sync:

{
  "phoneNumberId": "66f...",
  "category": "healthcare_reception",
  "appointmentScope": "global",
  "customApiBaseUrl": "https://YOUR_HMS_HOST/ondial",
  "customApiSecret": "YOUR_SHARED_SECRET",
  "slotsEnabled": true,
  "bookingEnabled": true,
  "copyVoiceFromAgentId": "OPTIONAL_TEMPLATE_AGENT_ID"
}

Then POST …/generate-script → POST …/activate. Hospital - sync then script then activate:

{
  "phoneNumberId": "66f...",
  "appointmentScope": "hospital",
  "branchId": "YOUR_BRANCH_ID",
  "customApiBaseUrl": "https://YOUR_HMS_HOST/ondial",
  "customApiSecret": "YOUR_SHARED_SECRET",
  "slotsEnabled": true,
  "bookingEnabled": true,
  "doctorsSyncEnabled": true,
  "copyVoiceFromAgentId": "OPTIONAL_TEMPLATE_AGENT_ID"
}

Doctor - sync then script then activate:

{
  "phoneNumberId": "66f...",
  "appointmentScope": "doctor",
  "branchId": "YOUR_BRANCH_ID",
  "doctorId": "YOUR_DOCTOR_ID",
  "customApiBaseUrl": "https://YOUR_HMS_HOST/ondial",
  "customApiSecret": "YOUR_SHARED_SECRET",
  "slotsEnabled": true,
  "bookingEnabled": true,
  "copyVoiceFromAgentId": "OPTIONAL_TEMPLATE_AGENT_ID"
}

Credit top-up stays on the Ondial dashboard or your existing billing flow; Public API exposes read balance and debit on purchase only.

Tenant webhook contract

Ondial POSTs JSON to customApiBaseUrl (the exact URL you configured - no path suffix is appended). Requirements

HTTPS in production
Respond within your configured timeout (default 8000 ms; patient lookup often 5000 ms)
When customApiSecret is set, expect Authorization: Bearer YOUR_SHARED_SECRET

POST /ondial HTTP/1.1
Host: YOUR_HMS_HOST
Authorization: Bearer YOUR_SHARED_SECRET
Content-Type: application/json

{
  "operation": "list",
  "use_case": "doctor_list",
  "branch_id": "YOUR_BRANCH_ID"
}

Locked ids: hospital and doctor scopes inject branch_id (and doctor_id for doctor scope) on every Custom API payload when missing. Global never injects a configured hospital - the caller-selected hospital is sent as chosen on the call.

`patient_lookup` - `read`

Request:

{
  "operation": "read",
  "use_case": "patient_lookup",
  "mobile": "+91XXXXXXXXXX",
  "branch_id": "YOUR_BRANCH_ID"
}

Response (found):

{
  "found": true,
  "row": {
    "name": "Patient display name",
    "patient_id": "YOUR_PATIENT_ID"
  }
}

Response (not found): { "found": false } Request: { "operation": "list", "use_case": "category_list" } Response:

{
  "values": [
    { "category_id": "YOUR_CATEGORY_ID", "name": "Cardiology" }
  ]
}

`hospital_list` - `list`

Request may include category_id and/or doctor_id filters.

{
  "values": [
    { "hospital_id": "YOUR_HOSPITAL_ID", "name": "Main campus" }
  ]
}

`doctor_list` - `list`

Request may include branch_id, hospital_id, category_id, and/or doctor_id.

{
  "values": [
    {
      "doctor_id": "YOUR_DOCTOR_ID",
      "name": "Dr Example",
      "specialization": "Cardiology"
    }
  ]
}

Used mid-call on global numbers and when you run Sync doctors on hospital/doctor agents.

`doctor_slots` - `list`

Request:

{
  "operation": "list",
  "use_case": "doctor_slots",
  "doctor_id": "YOUR_DOCTOR_ID",
  "branch_id": "YOUR_BRANCH_ID",
  "max_slots": 3,
  "filtered_date": "2026-09-01"
}

Response:

{
  "values": [
    {
      "slot_id": "YOUR_SLOT_ID",
      "datetime": "2026-09-01T09:30:00+05:30",
      "display_label": "Mon 1 Sep, 9:30 AM"
    }
  ]
}

`book_appointment` - `write`

Request:

{
  "operation": "write",
  "use_case": "book_appointment",
  "doctor_id": "YOUR_DOCTOR_ID",
  "slot_id": "YOUR_SLOT_ID",
  "patient_name": "Caller name",
  "mobile": "+91XXXXXXXXXX",
  "branch_id": "YOUR_BRANCH_ID"
}

Response:

{
  "success": true,
  "booking_id": "YOUR_BOOKING_ID"
}

record_id is also accepted as an alias for booking_id.

`lab_report` - `read` (optional feature)

When lab report inquiry is enabled on the agent:

{
  "operation": "read",
  "use_case": "lab_report",
  "inquiry_id": "YOUR_LAB_ID",
  "customer_phone": "+91XXXXXXXXXX"
}

Response: { "found": true, "row": { … } } or { "found": false }.

`prescriptions` - `read` (optional feature)

When prescription routing is enabled:

{
  "operation": "read",
  "use_case": "prescriptions",
  "prescription_id": "YOUR_RX_ID",
  "customer_phone": "+91XXXXXXXXXX"
}

Response: { "found": true, "row": { … } } or { "found": false }.

Failures

patient_lookup timeout or error → call still accepted (anonymous). Do not hang up.
Slots / book errors → return failure. Ondial must not confirm a booking your HMS rejected.

Validation

Rule	Result
`global` with `branchId` or `doctorId`	`422` `global_scope_locks_forbidden`
`hospital` without `branchId`	`422` `branch_id_required`
`hospital` with locked `doctorId`	`422` `hospital_scope_doctor_forbidden`
`doctor` missing `branchId` or `doctorId`	`422` `doctor_scope_ids_required`
Number not owned	`422` `phone_not_owned`
Sync doctors on a global agent	`422` `sync_not_allowed`

Create inbound agent
Update inbound agent
Sync doctors
List owned numbers
Activate
Inbound CRM lookup (dry-run read without a live call)
List calls
Credit transactions
Manage webhooks

Usage & call analytics

Build a wallet + call-log UI the same way production CRMs do: webhooks for near-real-time, poll APIs for catch-up.

Async billing (important)

Inbound voice flow:

POST /api/inbound/validate → session starts → Ondial may emit call.inbound.started
POST /api/inbound/call/end → transcript saved → call.inbound.completed with billingStatus: pending (no credits yet)
Carrier hangup / signed inbound-billing → credits deducted once → call.inbound.billed + credits.usage

Never compute cost from duration × a guessed rate. Use ledger amounts from webhooks or GET /api/v1/credits/transactions. call.inbound.billed / credits.usage and GET /api/v1/credits/transactions include fromNumber / toNumber (plus callerNumber / phoneNumber aliases), conversationId, and durationSeconds so wallet UIs can render From/To/DID without waiting for a separate calls merge. Prefer conversationId when joining to GET /api/v1/calls/{id} - callId may be a telephony UUID.

HMS checklist

API key scopes: calls:read, credits:read, webhooks:write; request opt-in analytics:read and recordings:read if needed.
POST /api/v1/webhooks with events: call.inbound.started, call.inbound.completed, call.inbound.billed, call.inbound.analysis, call.outbound.status, call.outbound.billed, call.outbound.analysis, outbound.lead.created, outbound.lead.updated, credits.usage.
Verify X-Ondial-Signature (HMAC-SHA256 of raw body). Prefer X-Ondial-Idempotency-Key for dedupe.
Upsert local rows by conversationId / callId + direction. On *.billed / credits.usage, update cost using usageId for idempotency. Requeues create a new callId - do not overwrite prior dials by contactId alone.
Poll GET /api/v1/calls and GET /api/v1/credits/transactions every 5–15 minutes and on UI open.
Live board: GET /api/v1/calls/active.
Aggregates: GET /api/v1/analytics/calls?groupBy=day.
Recordings: GET /api/v1/calls/{id}/recording (short-TTL signed URL).
Map each hospital/org → one Ondial account + API key.

Outbound status/billed events are defined for Ondial_Webhook / dialer to dispatch via POST /api/internal/tenant-webhooks/dispatch - see Ondial/docs/api-v1/OUTBOUND-TENANT-WEBHOOK-CONTRACT.md.

Get started

Send leads (outbound)

Answer calls (inbound)

Integrations

Concepts

Go live

Healthcare HMS integration

HMS platform checklist (end-to-end)

Phase 0 - Prerequisites

Phase 1 - Build the webhook (standard contract)

Phase 2 - Wire the agent in Ondial

Phase 3 - Runtime (live call)

Phase 4 - Ongoing management

Phase 5 - Go-live verification

Architecture

What you get

Setup in the dashboard

Setup via Public API (HMS admin)

Create examples

HMS admin UX (your platform)

Recommended screens

Server module (HMS codebase)

Buy-number sequence

Create agent after purchase (all scopes)

Tenant webhook contract

`patient_lookup` - `read`

`hospital_list` - `list`

`doctor_list` - `list`

`doctor_slots` - `list`

`book_appointment` - `write`

`lab_report` - `read` (optional feature)

`prescriptions` - `read` (optional feature)

Failures

Validation

Usage & call analytics

Async billing (important)

HMS checklist

​HMS platform checklist (end-to-end)

​Phase 0 - Prerequisites

​Phase 1 - Build the webhook (standard contract)

​Phase 2 - Wire the agent in Ondial

​Phase 3 - Runtime (live call)

​Phase 4 - Ongoing management

​Phase 5 - Go-live verification

​Architecture

​What you get

​Setup in the dashboard

​Setup via Public API (HMS admin)

​Create examples

​HMS admin UX (your platform)

​Recommended screens

​Server module (HMS codebase)

​Buy-number sequence

​Create agent after purchase (all scopes)

​Tenant webhook contract

​patient_lookup - read

​category_list - list

​hospital_list - list

​doctor_list - list

​doctor_slots - list

​book_appointment - write

​lab_report - read (optional feature)

​prescriptions - read (optional feature)

​Failures

​Validation

​Related APIs

​Usage & call analytics

​Async billing (important)

​HMS checklist

HMS platform checklist (end-to-end)

Phase 0 - Prerequisites

Phase 1 - Build the webhook (standard contract)

Phase 2 - Wire the agent in Ondial

Phase 3 - Runtime (live call)

Phase 4 - Ongoing management

Phase 5 - Go-live verification

Architecture

What you get

Setup in the dashboard

Setup via Public API (HMS admin)

Create examples

HMS admin UX (your platform)

Recommended screens

Server module (HMS codebase)

Buy-number sequence

Create agent after purchase (all scopes)

Tenant webhook contract

`patient_lookup` - `read`

`category_list` - `list`

`hospital_list` - `list`

`doctor_list` - `list`

`doctor_slots` - `list`

`book_appointment` - `write`

`lab_report` - `read` (optional feature)

`prescriptions` - `read` (optional feature)

Failures

Validation

Related APIs

Usage & call analytics

Async billing (important)

HMS checklist