In short
- An athenahealth API integration means your product reads or writes data in a practice's athenahealth environment through the APIs athenahealth exposes, either the standard FHIR R4 APIs a certified EHR must offer or athenahealth's own platform APIs, with the practice's permission.
- Federal certification rules give you a floor: a certified API must support FHIR R4, US Core, SMART App Launch and bulk export, and its developer must publish documentation, terms and fees and register apps on a set timeline.
- The work splits into five parts: confirm what the practice runs, choose standard or vendor APIs per feature, set up authorization, build reads before writes, and get the practice's sign-off.
An athenahealth API integration connects your product to a practice's athenahealth environment so it can read or write clinical and practice data through the APIs athenahealth exposes, with that practice's permission. You choose, feature by feature, between the standard FHIR APIs a certified EHR must offer and athenahealth's own platform APIs, then build, test and go live practice by practice.
This guide is for product and engineering leads at companies selling into independent practices and groups that run athenahealth. It describes the parts of the work that do not change: the federal rules behind certified APIs, the authorization patterns, and the order of work. athenahealth sets its own developer terms, onboarding steps and any fees, and those change. Read its current developer documentation before you commit to a plan.
What does an athenahealth integration connect?
Three kinds of products usually connect to athenahealth, and each wants different data.
- Patient apps and portals read a patient's medications, problems, allergies, results and visits, and sometimes write forms or home readings.
- Clinician tools, such as decision support or documentation aids, open in the context of a patient and read the chart while a clinician works.
- Back-office systems, such as a CRM, an RPM platform or an analytics pipeline, sync data in the background with no user signed in.
Write down which of these you are before choosing APIs. The type decides the authorization flow, who approves the app at the practice, and how much of the data you will need.
What must a certified athenahealth API support?
Where the athenahealth product your customer runs is certified to ONC's §170.315(g)(10) criterion, its API must answer requests for a single patient's data and for groups of patients. The criterion names the standards: FHIR R4, US Core (STU 6.1.0 as the base version, with later versions approved), USCDI v3 as the data set, SMART App Launch for authorization, OpenID Connect, and Bulk Data for group export. It also requires TLS 1.2 or above.
Two requirements matter for app design. On first connection, the certified API must issue a refresh token valid for at least three months to confidential apps and native apps that can secure one. And it must revoke an app's access within one hour when a patient asks. Your product has to handle both a long-lived connection and a sudden revocation.
Confirm which athenahealth product and version your customer runs before relying on any of this. Certification applies to a specific product, and the practice's IT contact can tell you which one they have.
What must athenahealth publish for developers?
The API Conditions of Certification at 45 CFR 170.404 apply to developers of certified API technology. As written, they require complete business and technical documentation at a public link with no preconditions, and publication of all terms and conditions, including fees, restrictions and registration requirements, with fees described in plain language. Cornell's copy of the rule links to an October 2026 amendment, so check the current text before you rely on a detail.
- Verification of an API user must be objective, applied the same way to everyone, and finished within ten business days of the request.
- Apps must then be registered and enabled for production within five business days after verification.
- Service base URLs that patients can use, with organization details, must be published at no charge as FHIR Endpoint and Organization resources and reviewed quarterly.
- Terms must not be less favorable than those offered to the developer's own businesses, and access cannot be conditioned on things like non-compete or exclusive-dealing agreements.
In practice, this means the documentation, terms and fees for the certified API should be readable before you sign anything. Read them first and list which agreements you need, with athenahealth and with each practice.
Should you use FHIR or athenahealth's own APIs?
Use the standard FHIR APIs where they cover the feature. They are the floor every certified EHR shares, so code written against them carries over to other EHRs, and the read side is predictable. US Core profiles tell you exactly what a lab result must contain: a laboratory category, a LOINC code where available, a status, a value with units, and supporting elements such as reference range and interpretation.
Use athenahealth's own platform APIs where the feature needs practice workflow that US Core does not cover, after checking athenahealth's documentation that the API you need exists and what it returns. athenahealth refers to these as athenaOne platform APIs, and in an August 2025 press release it said it was piloting a Model Context Protocol server on them for AI models. Treat vendor-specific APIs as a separate scope item with its own documentation, terms and testing.
Some practices also exchange data through HL7 v2 interfaces. The HL7 FHIR comparison notes that v2 is widely adopted, that most data elements are optional, and that mapping v2 messages to FHIR is generally done implementation by implementation. If a feature depends on a v2 feed, scope it as its own interface.
How does authorization work?
SMART App Launch gives you two patterns, and Backend Services gives you a third.
- EHR launch: the EHR opens your app with an iss parameter, its FHIR endpoint, and an opaque launch parameter that your app sends back during authorization. Clinician tools usually work this way.
- Standalone launch: the user starts in your app, which asks for context through scopes such as launch/patient. Patient apps usually work this way.
- Backend Services: a confidential client authenticates with a signed JWT and the client credentials grant, requests system scopes, and gets a short-lived token. The guide says expires_in should not exceed 300 seconds and that refresh tokens should not be issued.
Both launch flows require PKCE with the S256 method and validation of the state parameter. Plan where your keys live, who can rotate them, and how each practice's credentials stay in your company's name so they remain with you after the project.
In what order should you build?
- 1. Confirm the practice, its athenahealth product, and a sponsor who can approve access.
- 2. Map each feature to an API: standard FHIR, athenahealth platform API, or an interface. Note which are reads and which are writes.
- 3. Set up authorization and test it in the test environment.
- 4. Build the reads and show the practice its own test data in your product.
- 5. Add writes one at a time, each with a failure plan: queue, retry, and a visible pending state.
- 6. Test with the practice's configuration, then go live with a small group of users.
Building reads first gives the practice a working product early, and it surfaces data quality issues, such as missing codes or local test names, before anything is written back.
What does the practice need to approve?
The practice that uses athenahealth decides what your product may read and write. Bring a short packet to that conversation.
- The APIs and scopes you will use, with the feature behind each one.
- A data flow diagram: what leaves athenahealth, where it is stored, for how long, and who can see it.
- Every third-party service that touches the data, including hosting and error tracking.
- A signed or ready-to-sign BAA. We sign a BAA before anyone on our team sees PHI.
- Penetration test results. We run a penetration test before launch.
- How access is scoped. In the products we build, each clinician sees only their own patients.
What drives the timeline?
The number of writes, the number of vendor-specific APIs, and the practice's availability drive the timeline more than the read side does. A read-only patient app on standard APIs is the smallest version. A CRM that syncs both ways through vendor APIs is the largest. Agreements and approvals run in parallel with the build, so start them in the first week.
We have shipped Epic and athenahealth integrations, and for any vendor platform we work from the vendor's documentation and sandbox. If you are scoping an athenahealth integration, talk to one of our engineers. Our free five-day technical audit ends with a written report that lists the APIs, agreements and approvals your product needs.
Sources
- ONC (ASTP): §170.315(g)(10) Standardized API for patient and population services
- 45 CFR 170.404: API Conditions of Certification (Cornell LII)
- HL7 SMART App Launch 2.2.0: App Launch
- HL7 SMART App Launch 2.2.0: Backend Services
- HL7 US Core: Laboratory Result Observation profile
- HL7 FHIR R4: Comparison with HL7 v2
- athenahealth press release (August 14, 2025, via Silicon UK): AI-enabled interoperability and an MCP server pilot on athenaOne platform APIs