
If you are the technical lead at a healthcare group or a health-tech company, you will probably be asked to "sign off on the tech side" of a practice management system (PMS) purchase. The clinical and billing teams will have seen the demo. What they will not have seen is the API, and the API decides almost everything you will be able to do later: patient apps, analytics, integrations with new partners and, increasingly, AI workflows that need live access to schedules and claims.
Here is the due-diligence checklist we use, with the small probes we run in a sandbox before anyone signs.
1. Get a sandbox, not a PDF
A vendor that will not give you sandbox credentials before contract is telling you something about the next five years. Ask for:
-
A sandbox with realistic seeded data: providers, locations, slots, patients, coverage and some claims.
-
The same auth model as production (OAuth 2.0 with SMART on FHIR scopes is a good sign).
-
Rate limits documented and representative of production.
2. Map resource coverage, read and write
FHIR support is often described in one line on a sales slide. In practice, coverage varies resource by resource and operation by operation. Build a table for the resources you care about.
# fetch the server's declared capabilities
curl -s -H "Authorization: Bearer $TOKEN" \
"$FHIR_BASE/metadata" \
| jq '.rest[0].resource[] | {type, interactions: [.interaction[].code]}' \
| jq -c 'select(.type|IN("Patient","Appointment","Slot","Schedule","Coverage","Claim","Encounter"))'
Then verify, because the capability statement and reality do not always agree. Try to create an Appointment against a free Slot. Try to update Coverage. Many systems are read-mostly: fine for dashboards, a blocker for self-booking or scheduling agents.
3. Ask how change reaches you
This question shapes your architecture more than any other:
-
Push: webhooks or FHIR Subscriptions for appointment, registration and payment events.
-
Feed: HL7 v2 messages (ADT, SIU, DFT) through an interface engine, still common for older interfaces.
-
Poll only:
_lastUpdatedqueries on an interval.
Polling is workable, but it adds latency and load, and it is a poor foundation for a patient agent that needs to know a slot has just freed up. If events exist, ask about retries, ordering guarantees and replay after an outage.

4. Check the revenue-cycle data you can reach
If AI in the revenue cycle is on the roadmap (coding assistance, denial prediction, appeal drafting), you need programmatic access to:
-
Charges and claim lines with codes and modifiers.
-
Claim status and remittance data, including denial reason codes.
-
A way to write a flag, note or work-queue item back to a claim.
Without these, your denial model trains on spreadsheets exported by hand, and your suggestions live in a separate tool that billers forget to open.
5. Read the commercial terms like code
The API's cost structure is part of its design:
-
Per-call, per-record or per-integration fees.
-
Whether your own developers can build, or only certified partners.
-
Marketplace listing requirements if you are a health-tech company integrating with many practices.
-
Throttling that would make a nightly reconciliation impossible.
6. Test the exit
Ask for a full export in the sandbox and look at it. Is it documented? Does it include open balances, insurance history, recurring appointments and historical claims, or just demographics? How long does a production export take and what does it cost? A system you cannot leave is a system you cannot negotiate with.
7. Security and AI data handling
Confirm the basics: a signed business associate agreement, encryption in transit and at rest, MFA, role-based access, audit logs and independent attestations such as SOC 2 Type II or HITRUST. Then ask the newer questions: which AI features process patient data, which models, where, and whether that data is ever used for training.
A scorecard you can hand back
We summarise findings in a short scorecard so the non-technical owners can weigh them against specialty fit and cost:
pms_api_review:
sandbox_available: true
fhir_write:
Appointment: yes
Coverage: read_only
Claim: none
change_delivery: webhooks # webhooks | hl7_feed | poll_only
rcm_data_access: partial # claim status yes, remits via export only
own_developers_allowed: true
per_call_fees: false
full_export_tested: true
ai_data_policy_in_writing: pending
verdict: acceptable_with_conditions
That last line matters. Most systems are neither perfect nor unusable. The job is to know exactly which workarounds you are signing up for.
Where this fits in the bigger decision
The API is one input among several. Specialty templates, clean claim performance, patient experience, reporting and five-year cost are just as important to the practice. We walk through all of them, plus a vendor demo script and a six-step selection process, in our guide to the best medical practice management software.
If the audit shows gaps you need to build around, such as a patient app, an integration hub or an AI agent, our custom software development team builds those layers with the PMS kept as the system of record.
Frequently Asked Questions
Is a vendor's FHIR support statement enough to go on?
No. Coverage varies by resource and by operation. Check the capability statement, then test real reads and writes in a sandbox for the resources you plan to use.
What should we do if the PMS only supports polling?
Plan for it explicitly: incremental queries with last-updated filters, idempotent upserts and periodic full reconciliation. Also weigh it in the decision, because real-time use cases like patient agents suffer most.
Why does write access to Appointment matter so much?
Self-booking apps, waitlist engines and scheduling agents all need to create or change appointments. Without write access they can only display information and send people back to the phone.
Do we need HL7 v2 if the vendor supports FHIR?
Often yes. Labs, older interfaces and some hospital partners still exchange HL7 v2 messages, and some vendors expose events only through those feeds.
How do we evaluate the AI features a vendor is promising?
Ask which are generally available, which are in beta and which are roadmap only, then ask for written answers on which models are used, where data is processed and whether it is used for training.
What makes an API a lock-in risk?
Closed or partner-only access, per-call fees that scale with growth, missing write operations and exports that leave out billing history. Any one of these can make leaving or extending expensive later.