How PolyAI authenticates to AthenaOne, identifies or registers a patient, confirms or finds the physician, re-scopes its variant, validates and verifies insurance in real time for the appointment type, routes prescription refill requests to clinical pools, and books. Every node shows the request/response contract and, for each field, exactly where the data is sourced — captured from the caller, carried in conv.state from a prior call, set as a deployment attribute, or taken from the telephony ANI.
PolyAI runs as a backend client of AthenaOne's proprietary REST API. Unlike Epic (FHIR + private operations) or Cerner (standard FHIR R4), AthenaOne exposes a comprehensive proprietary REST API with over 800 endpoints, organised by practice ID. Patient reads, scheduling writes, insurance management, and clinical chart access all use the same RESTful pattern: /v1/{practiceid}/…. AthenaOne also has a native real-time eligibility check endpoint, reducing (but not eliminating) the need for the pVerify seam. Insurance is read from the patient record, confirmed with the caller, validated via the native eligibility endpoint or pVerify before any write, and (when valid) written back provisionally.
Every booking is assembled from reusable building blocks in this order. Each block sources its inputs explicitly and writes named outputs to conv.state for the next block.
Coverage is read early so the payer is available to the in-network provider filter in Find Physician; the caller-facing confirm/update happens in its own step and validates the plan before writing it to AthenaOne; the live benefit check then runs after physician + variant so the rendering NPI and the service-type (appointment type) are both present.
No component requires a human logged into AthenaOne — correct for inbound telephony. The agent operates strictly in the administrative lane (see Scope & Compliance).
Resolved against the AthenaOne API documentation. All endpoints are proprietary REST — AthenaOne does not use FHIR for its primary scheduling and patient management APIs. The “Native Eligibility” endpoint provides real-time 270/271 checks directly through AthenaOne, reducing pVerify dependency.
| Resource / service | Operation | Role in flows | Availability |
|---|---|---|---|
| Patient Search | GET /patients | Patient match / demographic search | REST API |
| Patient Search (broadened) | GET /patients | Fallback patient match — name + DOB only | REST API |
| Patient (create) | POST /patients | Create provisional new-patient record | REST API |
| Patient Insurance | GET /patients/{id}/insurances | Read insurance on file (payer + member ID) | REST API |
| Insurance Eligibility (native) | GET /insurances/{id}/eligibility | Real-time eligibility verification (270/271) | REST API |
| EligibilitySummary (pVerify fallback) | POST | Fallback real-time eligibility when native unavailable | pVerify seam |
| Patient Insurance (create) | POST /patients/{id}/insurances | Provisional patient-reported coverage write | REST API |
| Chart Encounters | GET /chart/{id}/encounters | Recent / historical provider | REST API |
| Providers | GET /providers | Resolve / find provider + NPI | REST API |
| Patient Appointments | GET /patients/{id}/appointments | Locate existing appointment | REST API |
| Open Appointment Slots | GET /appointments/open | Find available time slots | REST API |
| Appointment Book | PUT /appointments/{id} | Book appointment (fill open slot with patient) | REST API |
| Appointment Cancel | PUT /appointments/{id}/cancel | Cancel appointment | REST API |
| Appointment Reschedule | PUT /appointments/{id}/reschedule | Reschedule appointment | REST API |
| Appointments Booked | GET /appointments/booked | List booked appointments (confirm flow) | REST API |
| Appointment Check-in | PUT /appointments/{id}/checkin | Confirm / check-in (confirmation flow) | REST API |
| Chart Medications | GET /chart/{id}/medications | Retrieve active medications (refill flow) | REST API |
| Departments | GET /departments | Resolve department / location | REST API |
| Appointment Types | GET /appointmenttypes | List configured appointment types | REST API |
| User Message / Inbox Tasks | POST | Submit refill request to clinical inbox | REST API |
GET /appointments/open and booked via POST /appointments/{id}/book — a simpler, more direct model than Epic's $find/$book or Cerner's two-step Schedule+Slot pattern. Available slots change in real time; cache for no more than 5–10 minutes.conv.state, not regenerated.conv.state from a prior dip, a deployment/variant attribute, or the telephony ANI.conv.set_variant() re-points persona, department and appointment-type defaults the moment the provider is resolved.| Application | PolyAI |
| Prod Client ID | polyai-prod-… |
| API version | v1 · Proprietary REST · Practice-scoped |
| Grant | client_credentials (secret or JWT-based) |
| Token endpoint | https://api.platform.athenahealth.com/oauth2/v1/token |
| Scope | athena/service/Athenanet.MDP.* |
| pVerify (fallback seam) | OAuth2 client_credentials; when native eligibility insufficient |
Written for both PolyAI deployment teams and prospective clients. It states PolyAI's operating position and the design rationale. It is not legal advice; final determination that a deployment is permissible in its jurisdiction rests with the customer's legal, compliance, and clinical leadership.
Identifying and registering patients, finding the right provider and appointment type, confirming insurance, and booking are administrative functions — the same work a front-desk coordinator performs. They become the practice of medicine or nursing only when someone evaluates symptoms to determine clinical urgency or the type of care required. That boundary is the design.
The agent captures a reason-for-visit as an administrative label and maps it to a configured appointment type using the practice's own appointment-type configuration in AthenaOne. It does not interpret symptoms, rank severity, or select a specialty from a clinical presentation. “I need a cardiologist” or “my doctor referred me to dermatology” is administrative routing. “I have chest pain, what should I do?” is clinical — handled by the Safety-Net, not the agent.
Schmitt-Thompson protocols are the gold-standard telephone-triage decision support, used by the large majority of North American medical call centers — but they are physician-authored and administered by licensed nurses, peer-reviewed annually. PolyAI's decision is explicit: the agent does not run Schmitt-Thompson (or any) triage protocols and does not render dispositions. Where a caller introduces symptoms, the agent applies the Emergency Safety-Net and routes to the customer's licensed triage / clinical resource. Schmitt-Thompson stays with a licensed human.
New-patient registration and booking are administrative acts — automatable on the same basis as a human scheduler creating a chart and booking a visit — provided the interaction does not cross into symptom assessment or clinical triage. The flow collects identity and demographics, runs duplicate-matching, creates a provisional record (verified by staff at check-in), resolves an in-network provider, and books an administratively-mapped appointment type. The reason-for-visit is a routing label, not a clinical finding. That is what lets the function drive down patient leakage without becoming clinical decision-making.
Confirming insurance, validating that a plan is real and active, and running a real-time benefit check are administrative (financial / registration) acts with no symptom content, so they sit fully inside scope. One bright-line rule governs them: the agent surfaces the payer's determination; it never makes one. It reads back “your plan is active and covers this visit, your copay is $40,” or “the payer shows this plan as inactive — let me get you to billing.” It does not deny coverage, decide medical necessity, or issue an adverse benefit determination. This keeps the function clear of AI adverse-determination restrictions — for example Texas S.B. 815 (effective Sept 2025), which prohibits utilization-review agents from using AI to make adverse determinations. Patient-reported coverage is validated before it is written, and even then is written provisional; the authoritative truth is set by the payer's response and staff verification, not by the agent.
A conservative, customer-clinically-approved red-flag layer fronts every reason-for-visit. On a small set of unambiguous emergency cues — chest pain, difficulty breathing, stroke signs, severe bleeding, suicidal ideation — the agent stops the flow, instructs the caller to seek emergency care / dial 911, and warm-transfers to a designated clinical resource. It is tuned to over-escalate when uncertain. It is not triage: it assigns no disposition and no level of care — it removes the highest-risk interactions from the automated path entirely.
PolyAI provides the mechanics: the administrative flows, the reason→appointment-type mapping, the escalation routing, the data lineage, and the eligibility seam. The health-system customer owns the clinical content: the emergency red-flag set, the escalation targets (nurse line, 911 guidance, warm transfer), the appointment-type configuration, and clinical governance.
Established-patient flows. Pick one; decisions fan out into labelled branches with their own terminals — loop-backs, CC handoffs, the continuing path. Click any node for utterances, request/response contracts with per-field data provenance, fallbacks, and capture strategy. New-patient intake has its own section. Click a building block to drill in.
The high-value, higher-care flow. A caller with no record wants to be seen. The agent runs the Safety-Net, matches against existing records to avoid a duplicate, registers a provisional record only on no-match, takes insurance up front (so the provider search can filter in-network), validates the plan before writing it, finds a provider accepting new patients, re-scopes its variant, verifies benefits live, and books a new-patient appointment type.
| Concern | Established patient | New patient |
|---|---|---|
| Record | Exists — resolve Patient ID | May not exist — demographic match, then create only on no-match |
| Duplicate risk | Low | High — ambiguous match → data-stewardship handoff, never auto-create/merge |
| Insurance | On file → confirm, validate, update if changed | None on file → capture up front + validate before write (needed for in-network search) |
| Provider | Confirm the one they've seen | No history — directory search (specialty + location + accepting-new + network) |
| Appointment type | Established appointment types | New-patient appointment types (longer; different codes) |
| Booking write | POST /appointments/{id}/book | POST /appointments/{id}/book (same endpoint) |
Voice ASR makes some fields risky. These are the patterns PolyAI uses — validate against known values first, fall back to spelling only when needed, and treat reason-for-visit as an administrative label, never a clinical assessment.
Grouped by call flow. Each use case shows the APIs it needs, how many times each is called, and whether it costs anything beyond the standard EHR license. Expand any API for the full request/response contract with per-field data provenance.
Every API card carries four badges. Here’s what each one means.
Which system handles the API call.
| AthenaOne | Call handled by the AthenaOne proprietary REST API server. |
| pVerify | Call leaves the EHR and hits pVerify, a third-party eligibility clearinghouse (fallback). |
The API tier within that platform.
| REST API | Standard AthenaOne proprietary REST endpoint. Included with the athenahealth subscription. No per-call fees; no vendor-gated tier system. |
| Clearinghouse | X12 270/271 transaction routed through pVerify. Separate vendor, separate contract. |
How the API is priced at runtime.
| Included | Included with athenahealth subscription. No per-call fees. Cost does not scale with call volume. |
| Per-Use | Per-transaction pricing (pVerify clearinghouse only). |
Expected calls per patient conversation.
| 1× | Called once per conversation. |
| 1× fallback | Called only if the primary lookup returns no results. |
| 1× cond. | Called conditionally (e.g., insurance changed, controlled substance, overdue patient). |
| 1–3× | May loop — e.g., slot negotiation when the caller requests different times. |
| 1× cond. | Red-tinted when the API is Per-Use — flags a per-transaction cost. |
Unlike Epic (which uses a seven-tier Class A–G per-transaction model for Private APIs) or Cerner (which bundles everything under the Millennium Platform license), AthenaOne uses a subscription-based model where API access is included with the athenahealth service subscription.
GET /insurances/{id}/eligibility that performs a 270/271 transaction natively. This reduces pVerify dependency to a fallback role — pVerify is only needed when the native check is insufficient (e.g., specific benefit detail not returned, non-EDI payer, or practice preference). This is a significant cost advantage over Epic and Cerner deployments.Model how many API transactions each use case generates per month. The estimator accounts for caller drop-off through the flow, multi-intent calls where the patient is already identified, and conditional steps that only fire in certain paths.
How many patient conversations per month will the PolyAI agent handle for each use case? These are intents — a single call may contain multiple intents (see Multi-Intent below).
What percentage of conversations complete the full flow (reach the final write/booking step)?
What percentage of callers complete more than one task per call?
OAuth 2.0 client_credentials with either a client secret or a signed JWT assertion. No interactive login — correct for an inbound call where no clinician or patient can complete a browser consent. The same token serves all AthenaOne REST API calls. The pVerify eligibility seam (when used as fallback) uses its own OAuth2 token.
| OAuth flow | Designed for | Voice-suitable? | Why |
|---|---|---|---|
| Client Credentials Use | Server-to-server, no user present | Yes | Client ID + secret (or JWT); Agent Studio auto-refreshes the token. |
| Authorization Code No | User-facing apps with browser redirect | No | Needs a browser consent screen — impossible on an inbound call. |
| Patient Portal No | Patient-facing portal apps | No | Needs patient portal credentials + browser consent. |
Build with Poly Agent Builder (non-technical) or the ADK (developers) — same dialog-native runtime. The data-lineage discipline below is what makes the deployment auditable.
Configure > Integrations > AthenaOne. Register the application via the athenahealth Marketplace / developer portal; production access requires athenahealth approval. Configure practice ID(s) and OAuth credentials. (pVerify provisioned separately as fallback.)
Configure > APIs: declare each endpoint with environment-specific base URLs and OAuth 2.0. All operations use the proprietary REST API — no FHIR or vendor-gated tiers. Configure insurance write and eligibility check endpoints.
Each function reads inputs from a declared source — caller capture, a conv.state value from a prior dip, a variant attribute, or ANI — calls conv.api.athena.<op>(...), and writes named results back to conv.state.
The moment Confirm/Find Physician resolves a provider, call conv.set_variant(specialty) and write provider / department / appointment-type to conv.state so every downstream {{attr:…}}, slot search and write re-points.
Front every reason-for-visit with the customer-approved red-flag set; map reason→appointment type via the configured type mapping; validate coverage via native eligibility (or pVerify fallback) before writing; run the live benefit check after physician + variant. Keep clinical content as customer-owned configuration.
The agent checks the patient's active medications, computes remaining refills, verifies visit eligibility (12-month lookback), and routes the request to the appropriate clinical pool. Controlled substances require an in-person visit. The agent never dispenses, adjudicates, or overrides — it routes.
| Scenario | Agent action | API surface |
|---|---|---|
| Refills remaining on file | Direct caller to their pharmacy — no request submitted | GET /chart/{id}/medications (read) |
| No refills remaining — visit within 12 months | Submit refill request to clinical pool | POST User Message / Inbox Task |
| No refills remaining — no visit in 12 months | Schedule a visit and submit refill request | GET /appointments/open + POST /appointments/{id}/book + POST message |
| Controlled substance | Schedule in-person visit; submit request with HIGH priority | POST /appointments/{id}/book + POST message (priority: urgent) |
| Clinical question about medication | Transfer to staff | No API — CC handoff |
GET /chart/{id}/medications response should be confirmed against the current API documentation. The medication record structure may use different field names than shown above.The reasoning behind each choice, so it holds up to clinical and technical review.
Surfaces that exist in the AthenaOne ecosystem and could plausibly have been used here, with the reason each was set aside for this conversational, real-time, administrative use case.