APIs in Healthcare

What are APIs in healthcare?

APIs in healthcare are documented interfaces that let authorized software read, write or subscribe to clinical, financial and operational health data. Most modern ones use HTTPS and JSON, with HL7 FHIR R4 for clinical and payer data, SMART App Launch for authorization, and older standards such as X12 and DICOMweb for claims and imaging.

Two questions shape every healthcare API decision: whose data is being accessed, and on whose authority. A patient reading their own record, a clinician working inside the chart and a nightly analytics job each need a different authorization flow, even when they call the same endpoint.

Which categories of healthcare API exist?

Healthcare APIs fall into six broad categories. Most products touch at least two, and each category has its own standards, gatekeepers and onboarding steps.

• Clinical EHR APIs: FHIR R4 resources profiled by US Core, SMART on FHIR launch for embedded apps, CDS Hooks for decision support cards at points such as patient-view and order-sign, and Bulk Data for population exports.
• Payer APIs: FHIR Patient Access, Provider Access, Payer-to-Payer and Prior Authorization APIs under CMS rules, alongside X12 eligibility, claim and remittance transactions usually reached through a clearinghouse.
• Pharmacy APIs: e-prescribing networks built on the NCPDP SCRIPT standard, plus prescription benefit checks offered through those networks.
• Imaging APIs: DICOMweb services defined in DICOM PS3.18, with QIDO-RS for queries, WADO-RS for retrieval and STOW-RS for storing studies.
• Device and consumer APIs: Apple HealthKit and Android Health Connect on the phone, and vendor clouds for blood pressure cuffs, scales and glucose monitors.
• Vendor-specific APIs: proprietary EHR and practice management endpoints for scheduling, billing and documents, which go beyond the certified standard.

Who controls access to each category

Each category has a gatekeeper, and onboarding with that gatekeeper often takes longer than writing the client code. Plan for it from the first week.

• EHR vendors: developer programs such as open.epic and fhir.epic.com register apps and issue client IDs; each health system then decides whether to enable the app in its own environment.
• Payers: CMS-regulated payers publish developer documentation and registration steps for their FHIR APIs, and X12 traffic usually runs through a clearinghouse agreement.
• Pharmacy networks: e-prescribing connections require certification with the network before production traffic is allowed.
• Device makers: vendor clouds issue API keys under partner terms, and the patient must authorize each connection.

Read, write and event access

Read access is the most standardized, write access the least, and event access sits in between. Planning a product around that split avoids promising features the target systems cannot deliver.

Read: the certified API under 45 CFR 170.315(g)(10) is a read API for patient and population services. It returns USCDI data through US Core profiles and works across certified EHRs with modest per-vendor work.

Write: booking appointments, filing flowsheet rows, posting charges or sending notes back to the chart needs the EHR vendor's own write APIs or an HL7 v2 interface. Support differs by vendor and often by site, so confirm each write in the target environment before quoting it to a customer.

Events: an app that needs to know when something changes can use FHIR Subscriptions where the server offers them, vendor webhooks, or an HL7 v2 ADT or results feed. Polling a cloud EHR for every patient on a timer wastes rate limits and still lags.

What do regulators require of health APIs?

Regulation sets the minimum API surface for certified developers and payers, and security standards set the minimum for everyone else.

• Certified API: 45 CFR 170.315(g)(10) requires certified health IT to support a standardized FHIR read API with SMART App Launch and Bulk Data.
• Payer APIs: CMS-0057-F requires impacted payers to offer Prior Authorization, Provider Access and Payer-to-Payer APIs from 1 January 2027, extending the Patient Access API that CMS-9115-F introduced.
• Information blocking: for actors under 45 CFR Part 171, API terms, fees or technical barriers that are likely to interfere with access can be information blocking unless an exception applies.
• HIPAA Security Rule: 45 CFR 164.312 requires access control, audit controls and person or entity authentication for systems holding ePHI; transmission encryption is addressable, and the rule names no specific protocol.
• OWASP API Security Top 10 (2023): ranks Broken Object Level Authorization first, followed by Broken Authentication, Broken Object Property Level Authorization and Unrestricted Resource Consumption.

What does a secure healthcare API check on each call?

Secure it by context: authenticate the caller with the right flow, then check on every request that the caller may see this specific patient's data. Authentication alone is not authorization.

• Patient apps: SMART standalone launch with OAuth 2.0 and PKCE, patient-level scopes and refresh tokens tied to the patient's grant.
• Clinician apps: SMART EHR launch, which passes launch context such as the current patient and encounter into the token response.
• Server-to-server jobs: SMART Backend Services, where the client signs a JWT with its private key and receives system-level scopes.
• Narrow scopes: request SMART v2 scopes such as patient/Observation.rs rather than wildcards; security reviewers at health systems approve narrow requests more readily.
• Object-level checks: verify ownership on every resource ID, including those reached through _include, references and paging links.
• PHI out of URLs: send sensitive search parameters in a POST _search body so names and birth dates do not land in access logs, CDN logs or traces.
• Rate limits: cap request rates and page sizes per client, which addresses the resource consumption risk OWASP lists.
• Audit trail: record actor, client ID, patient, resource, action and time for each access, in a store separate from the application database.

Handling tokens and keys

Tokens are PHI keys in practice, so treat them like secrets. Keep access tokens short-lived, store refresh tokens encrypted on the server rather than in a browser, and never log them.

For backend services, keep the private signing key in a managed key store, publish the public key through a JWKS URL the EHR can fetch, and rotate keys on a schedule. A rotation that is never rehearsed tends to fail on the day a key is exposed.

Contracts follow the data flow. A vendor that handles PHI on behalf of a covered entity is a business associate and needs a business associate agreement under 45 CFR 164.502(e). An app the patient chooses for their own access is not the provider's business associate, according to HHS guidance, though the app may fall under the FTC Health Breach Notification Rule.

API design decisions to settle early

These decisions are cheap in the first sprint and costly after partners connect. Settle each one in writing.

• Resource model: expose FHIR resources where partners expect them; use a custom model internally only behind an adapter, never leaking it into partner contracts.
• Vendor adapters: wrap each EHR, payer or clearinghouse behind an internal interface that hides its pagination, error codes and token refresh.
• Versioning: decide how API versions are named, how long old versions live and how deprecation is announced.
• Idempotency: require an idempotency key or client identifier on create calls so retries never duplicate an order, observation or claim.
• Errors: return FHIR OperationOutcome on FHIR endpoints, with an issue code a client can act on.
• Paging: use the Bundle next link rather than offsets, so large result sets stay consistent while data changes.
• Events: choose webhooks or subscriptions over polling, and document retry and signature rules for receivers.
• Sandbox: publish synthetic patients and test credentials so partners can build without real data.
• Observability: track latency, error rate and quota use per client and per partner, so a slow EHR is visible before customers report it.

Write these choices into a short API standard that every service follows. A new engineer should be able to read one page and know how to name, page, version and secure an endpoint.

Why do healthcare API launches stall?

Most stalled launches trace back to a short list of failure points, and each one can be caught in design review.

• Promised write-back: committing to write data into the EHR before confirming the vendor and site support that write in production.
• Missing object checks: relying on the user interface to hide other patients' records instead of checking ownership on the server.
• Vendor quirks in core code: building one EHR's extensions into product logic, so the second health system becomes a rewrite.
• Untranslated codes: returning local lab names or uncoded problem text, which forces every consumer to write its own parser.
• Late app registration: leaving vendor developer program enrollment, security questionnaires and production credentials until the code is done.
• No sandbox parity: testing only against a vendor sandbox whose data and limits differ from the production site.

How Agnotic can help

API architecture decisions are usually made before a health startup has senior engineers to make them. Agnotic Technologies provides healthcare fractional CTOs who set the API categories, authorization flows, adapter boundaries and design rules, and engineers who then build the FHIR endpoints, SMART on FHIR apps and payer connections for the client.

Sources

• ASTP/ONC: Standardized API for patient and population services, 45 CFR 170.315(g)(10)
• HL7: SMART App Launch implementation guide
• HL7: CDS Hooks specification
• CMS: Interoperability and Prior Authorization Final Rule (CMS-0057-F)
• 45 CFR 164.312: HIPAA Security Rule technical safeguards
• HHS OCR: The access right, health apps and APIs
• OWASP: API Security Top 10 (2023)
• DICOM Standard: DICOMweb (PS3.18)