This one is technical. If you run a practice and you are not the technical one, forward it to whoever handles your IT. If you are the technical one, or you just want to know what integrates with athenahealth actually means when a vendor says it, read on.
MedPhone is a HIPAA compliant AI phone agent for medical practices and an athenahealth Marketplace Partner. Synergy Medical, a family medicine practice in Michigan, runs it in production against athenahealth every day. This is what building on that API looks like from the vendor side. What works, what is hard, and what I wish athenahealth would build.
What the Marketplace Partner API actually exposes
Marketplace Partner access is a specific tier of the athenahealth API. Getting it means partner review, sandbox testing, and eventual production certification. You do not simply sign up. The bar is real and the review is thorough.
Once you are through, the endpoints that matter for a phone agent are these.
- Patient lookup. Search by name, date of birth, phone number or a combination, returning demographics, active appointments and clinical inbox tasks
- Provider schedule retrieval. Pull the open slots for a provider across a date range, with slot types honored, so new patient, follow up and procedure stay distinct
- Appointment booking. Create or reschedule, with appointment type, provider, location and reason
- Appointment cancellation. Cancel with a reason code, releasing the slot back into the schedule
- Clinical inbox tasks. Create tasks for refill requests, referrals or anything else needing a provider decision, landing in the provider inbox for review
- Chart notes. Append a call summary to the patient chart recording exactly what was done on the call
There is more surface area than that, but those are the endpoints a phone agent touches on essentially every call.
The three hard problems
Any AI phone agent claiming deep athenahealth integration has to solve these three. If a vendor cannot describe how they handle each one, be skeptical.
One: latency against a live conversation
A phone agent works in real time. Someone says they want to reschedule, and the reply has to land within a second or two or the conversation feels broken. That reply depends on knowing which appointments the caller has and which slots are genuinely open, and both of those are API calls.
Healthcare APIs, athenahealth included, are not built for conversational latency. They are tuned for batch workflows and dashboard queries, which is a completely reasonable thing for them to be tuned for. It just is not the budget a voice agent is working inside.
We handle it with parallelization and a bit of speculation. The moment intent is detected, the patient lookup and the schedule query fire together, so by the time the caller has finished their sentence the data is already in memory. Common provider schedules are pre fetched on the heaviest days at a practice so the schedule is warm before anyone dials. Everything we claw back from API time goes to the voice model and the network hop back to the caller, which is where it is actually audible.
Two: rate limits
Marketplace Partner access comes with rate limits. They are reasonable, and they still matter. A busy practice can take thirty to fifty calls in a peak hour, each one firing several API requests, and that multiplies across every practice on the platform.
The obvious response is to cache harder. The problem is that schedule data goes stale in seconds. A cached slot can be booked by a human at the front desk while the agent is busy offering it to a caller, and now you have a double booking and an angry practice manager.
So the cache windows on schedule data are short, sixty seconds at most, and every booking gets a final availability check immediately before we confirm anything to the caller. If the slot has gone, the agent falls back to the next best option. If nothing fits the stated preference, it transfers to a human rather than improvising.
Approaching the rate limit triggers exponential backoff and graceful degradation. Individual calls fail over to a human transfer rather than sit there taking longer than a caller will tolerate. A slow answer is worse than a handoff.
Three: reconciliation
This is the specific case where the agent and a front desk staffer book the same slot at the same moment. Both requests reach athenahealth, athenahealth honors the first and rejects the second, and one of those two parties has to handle the rejection live, mid sentence, without the caller noticing anything has gone wrong.
Every booking is therefore tentative until athenahealth confirms it. On a rejection the agent apologizes, says the slot was just taken, and offers the next option. We track reconciliation failures per practice as a quality metric, because a high rate is a real signal: it means the agent is competing with a very busy front desk for the same slots, and the practice usually wants it booking at different intervals or in specific windows instead.
Why Marketplace Partner status is not just a badge
There is a meaningful difference between we integrated with athenahealth and we are a verified Marketplace Partner.
An unofficial integration, which in practice often means screen scraping or unsanctioned API access, has three problems. It can be shut off at any time by an auth change. It breaks on releases with no warning. And it puts PHI somewhere that was never reviewed for security.
Partner status means the integration has been reviewed by the athenahealth partner engineering team, that there is sandbox access for pre production testing, that breaking changes come with notice, and that there is a documented API contract underneath rather than a scraper held together with hope. For a practice IT team running procurement, that is the difference between a vendor who can operate at scale and one who is a single release away from breaking every customer at once.
A real call, start to finish
Here is the sequence for a reschedule, taken from production logs. Names are changed and the endpoint shapes are simplified, but the ordering and the timings are real.
| What happens out loud | What happens underneath |
|---|---|
| Caller: I need to reschedule my appointment | Intent detected, lookups queued |
| Agent: Sure, can I get your first and last name? | Patient search returns the record, then active appointments, roughly 200ms in parallel, cached for the rest of the call |
| Agent: I see you have an appointment with Dr. Reyes on Thursday at 9. Reschedule that one? | Patient context already in memory, no further call needed |
| Caller: Yes, that one. Agent: Let me pull her schedule | Provider schedule query for the surrounding date range |
| Agent: She has Tuesday at 10 or Wednesday at 2. Which works? | Open slots filtered by matching appointment type |
| Caller: The 10. Agent: One moment | Cancel the original, book the new slot, write the call summary to the chart. All three must succeed together |
| Agent: Booked. You are moved to Tuesday at 10 with Dr. Reyes, and you will get a text confirmation shortly | Confirmation dispatched, original slot released back to the schedule |
Total call time, 47 seconds. Chart updated, slot released, confirmation sent. If any of the writes fails, the agent rolls back and offers a transfer rather than leaving the schedule in a state nobody can reason about.
What athenahealth still cannot do
Being straight about the limits. The Marketplace Partner API is capable, and there are three things it does not do well today.
- Real time availability push. We poll. Polling schedules to catch last minute changes eats API budget that would be better spent elsewhere. A webhook or streaming mechanism would tell us the instant a slot opens or closes
- Cross department scheduling. Multi department practices want the agent to route on intent and then book in the right department. That works today, but it needs custom logic per practice because department mapping is not surfaced consistently
- Insurance verification during a live call. The verification workflows exist, they are just not shaped for voice latency. Callers asking to verify coverage mid booking get transferred to a person, which is the correct conservative behavior and still adds friction
None of these are dealbreakers. All of them are places the platform could get better.
The one endpoint I would ask for
If anyone at athenahealth reads this: a slot reservation endpoint would change our lives.
The shape is simple. Tentatively hold a slot for sixty seconds while we confirm with the caller. If they accept, convert the hold into a booking. If they decline or the call drops, it expires and the slot goes back.
We do this today with a lock table on our side and best effort reconciliation. It works. It is also fragile in exactly the way you would expect something reimplemented outside the system of record to be. Native reservation semantics would let every partner build faster and safer, not just us.
If you are evaluating a vendor
Building on athenahealth is not the hardest engineering problem I have worked on, but it is a good one. The partner review forces you to think properly about security, error handling and rate limits, the surface area is rich enough to build a real product on, and the support relationship is genuine.
If you are looking at an AI phone vendor that claims deep athenahealth integration, everything in our HIPAA vendor checklist applies, plus three technical questions.
- Are you a verified Marketplace Partner, or an unofficial integrator?
- How do you handle reconciliation when a slot gets booked twice at once?
- What is your API response time budget per call, and what happens when you blow through it?
Vendors who can answer those specifically are worth your time. Vendors who cannot are not.
Read the HIPAA vendor checklist
Questions people ask
Is MedPhone the only AI phone agent on the athenahealth Marketplace?
No. There are others, with different products and different tradeoffs. If you are on athenahealth, get demos from every Marketplace Partner in this category and compare them properly.
Do we need anything special from athenahealth to use MedPhone?
You need to be an athenahealth customer. That is it. MedPhone works with any athenahealth practice.
How long does the Marketplace Partner review take?
About three months for us, from application to production certification. Yours will vary with how much of the security and error handling work you have already done before you apply.
Can we see it running against a live athenahealth environment?
Yes. Book twenty minutes and we will walk through the production setup at Synergy Medical rather than a sandbox demo.
Agni Patel is the founder and CEO of MedPhone. He wrote the first version of the athenahealth integration himself.
