Nirmitee.io

For health tech products

athenahealth Integration Services

We build athenahealth integrations for health tech products: patient apps, provider SMART apps that open inside athenaOne, back-end sync, Event Notifications consumers and HL7 v2 interfaces. We also run the access path with you, from the first Preview app to Solution Validation and practice enablement. For endpoint-level detail, read our athenahealth API integration guide.

Plan my athenahealth integration

For digital health products, practice networks and healthcare software teams selling into athenaOne practices. Updated October 2026.

What we build on athenahealthPatient appsProvider SMART appsBack-end syncEvent NotificationsHL7 v2 via Mirth
Evidence you can check
  • ISO 27001:2022 certified
  • HIPAA-enabled: we sign BAAs
  • SMART on FHIR app run against the Epic and Oracle Health developer sandboxes in one session
  • Our team has built 350+ interfaces on Mirth Connect

The problem

Sound Familiar?

What health tech teams tell us when they start building on athenahealth.

The FHIR API will not let us book

FHIR reads work, but booking, documents and registration need the athenaOne APIs and a Platform Services contract.

Our provider app cannot be tested

A clinician-facing SMART app needs a Preview tablespace from a customer or the partner program, not the public sandbox.

Validation keeps moving the date

Each endpoint goes through Solution Validation, and new endpoints added later go through it again.

Every practice is set up differently

Departments, providers and appointment reasons differ by practice, so a booking that works in one fails in another.

Use cases

What It Looks Like When It Works

Four use cases, each shown as the console your team works in. The practices and patients are fictional; the athenahealth rules behind each screen are real.

An Access Path With Owners and Dates

Today

The contract, the Tech Spec and validation are discovered one at a time, after the code is written.

With the integration

Every step from the Preview app to practice enablement has an owner and a status, and the slow ones start on day one.

What we build
  • Preview app and first calls the same day
  • Tech Spec written from the code being built
  • Solution Validation evidence prepared with you
athenahealth access path tracker from Preview app to Platform Services contract, Tech Spec, Solution Validation and practice enablement
Illustrative screen with fictional patients and practices: athenahealth access path tracker from Preview app to Platform Services contract, Tech Spec, Solution Validation and practice enablement. Tap to open full size.

Practice Setup Checked Before Launch

Today

A practice turns on the app and bookings fail because a department or appointment reason is missing.

With the integration

Departments, providers and patient appointment reasons are checked practice by practice before launch, with gaps shown in plain words.

What we build
  • Per-practice configuration kept out of code
  • A setup check for each new practice
  • An onboarding runbook your team can repeat
Practice setup check showing departments, mapped providers and web booking reasons for three athenahealth practices
Illustrative screen with fictional patients and practices: practice setup check showing departments, mapped providers and web booking reasons for three athenahealth practices. Tap to open full size.

Bookings Through the athenaOne APIs

Today

Staff copy bookings from your product into athenaOne by hand.

With the integration

Bookings are written through the athenaOne APIs with a patient appointment reason, confirmed in athenaOne, and a taken slot offers the next one.

What we build
  • Booking with the appointment reason each practice uses
  • Token caching inside the production limits
  • Clear results when a slot is no longer free
Booking log showing appointments written through athenaOne APIs, confirmed, with a taken slot offered the next opening
Illustrative screen with fictional patients and practices: booking log showing appointments written through athenaOne APIs, confirmed, with a taken slot offered the next opening. Tap to open full size.

Changes Pushed, Not Polled

Today

The product polls for changes, hits limits and still shows stale appointments.

With the integration

Event Notifications arrive at a receiver that checks the signature, answers within 2 seconds, queues the work and retries before sending anything to a dead-letter queue.

What we build
  • HMAC signature checks on every event
  • A durable queue behind the endpoint
  • Retries and a dead-letter queue you can inspect
Event Notifications receiver showing signature checks, response times and queued processing for athenahealth events
Illustrative screen with fictional patients and practices: event Notifications receiver showing signature checks, response times and queued processing for athenahealth events. Tap to open full size.

First call

Questions We Will Ask You on the First Call

The answers decide the app types, the API family and the access steps.

Which athenahealth product do your customers use?

athenaOne and athenaPractice or athenaFlow use different portals and sandboxes.

Is your app for patients, clinicians or back-end jobs?

Each app type is registered separately, and one credential set cannot do both.

Do you need to book, post documents or register patients?

Those run on athenaOne APIs under a Platform Services contract, not on FHIR.

Do you have a customer who can provide a Preview tablespace?

Provider apps and bulk export cannot be tested in the public sandbox.

How fresh must your data be?

Event Notifications avoid polling where your contract allows them.

How many practices will you onboard first?

Each practice has its own departments, providers and appointment reasons to check.

Do you want a Marketplace listing?

The Marketplace Partner Program is something your company joins and holds.

Who owns the athenahealth agreement?

Your organization or your customer does; we prepare the Tech Spec and validation evidence with you.

What we build

Five things we build on athenahealth.

Most products need two or three of these together. A patient booking app, for example, pairs a 3-legged patient app with a 2-legged service that books slots and listens for changes. We scope each piece against what athenahealth actually allows for your app type.

01

Patient-facing apps

SMART standalone patient launch

Portals, intake, booking and remote care apps that sign the patient in through athenahealth's Okta-based OAuth server with the authorization code flow, PKCE and a nonce (athenahealth rejects an openid request without one). We read the patient's chart through the certified FHIR R4 API and handle 60-minute access tokens and 90-day refresh tokens. Patient apps can be tested end to end against athenahealth's public Preview test patient, so this is the fastest path to a working demo.

02

Provider SMART apps inside athenaOne

EHR launch from the clinician's workflow

Prescribing, documentation, decision support and review tools that a clinician opens from inside athenaOne as an embedded app. The launch passes patient, encounter and order context, and the app requests user-level SMART scopes. Where you need cards during ordering, athenahealth supports CDS Hooks for the order-select hook only, under an updated API Solutions contract. We plan the testing environment early, because provider apps only authenticate through an EHR launch.

03

2-legged back-end sync

Service-to-service, no user in the loop

Services that search patients, pull clinical data, book appointments or post documents on a schedule. They use the OAuth client_credentials grant with system-level FHIR read scopes and the athenaOne service scope. We build a token service that caches the hourly token instead of requesting a new one per call, and a request budget that stays inside athenahealth's production limit of 150 requests per second and 500,000 per day for your app.

04

Event Notifications consumers

Push, not polling, where your contract allows it

Webhook receivers for athenahealth's Event Notifications (FHIR Subscriptions): rest-hook, id-only payloads, HMAC signature checks, a 2-second response budget and a durable queue behind the endpoint so retries and the dead-letter queue never become data loss. Event Notifications need a 2-legged app and an updated API Solutions contract; where that is not yet in place we build on changed-data subscriptions and poll them within athenahealth's retention windows.

05

HL7 v2 through Mirth Connect

When the practice already runs interfaces

ADT, SIU scheduling, DFT charges, ORM orders and ORU results that travel as HL7 v2 over SFTP or a site-to-site VPN rather than API calls. We build and run the Mirth Connect channels, mapping, acknowledgements, alerting and replay, and keep the interface and API paths reconciled when a product uses both.

Two API surfaces

Read through FHIR. Act through athenaOne.

Certified FHIR R4 API

Where clinical data is read

athenahealth's certified FHIR APIs are free to use and built for reading US Core data. On the production CapabilityStatement we checked in September 2026, every resource type allowed read and search, and QuestionnaireResponse was the only one that allowed create. FHIR write scopes are not granted by default.

  • Patient, encounter, problem, medication and result reads
  • Bulk FHIR export per practice for initial and monthly loads
  • SMART v1 and v2 scopes, system scopes for back-end apps
Output: a resource and scope list tied to each screen and job in your product.
athenaOne APIs

Where the practice's work gets done

Booking and rescheduling appointments, posting clinical documents, patient registration and changed-data feeds run on athenaOne endpoints, which athenahealth bills by call volume. Web booking must use a patient appointment reason, and documents land in the clinical inbox for review.

  • Scheduling with reason IDs and department context
  • Clinical documents and encounter-level write-back
  • Changed-data subscriptions for near real-time sync
Output: a workflow-level integration contract, endpoint by endpoint.

What athenahealth enforces, and how we design for it

150 / 500,000
Production requests per second and per day, per app (15 and 50,000 in Preview). We size polling and backfills to fit.
60 minutes
Access token lifetime. New 2-legged token requests are capped per minute, so tokens are cached and shared.
Per endpoint
Solution Validation covers the endpoints you declared. Calling one outside that list returns an error in production.
Per practice
Each athenaOne practice enables your app before your credentials can read its data.

From Preview to production

How an engagement runs.

The access path decides the calendar more than the code does, so we start it on day one and build in parallel.

01

Preview credentials, then a test tablespace

We register your app in the athenaOne Developer Portal console (2-legged, 3-legged patient or 3-legged provider; one credential set cannot do both) and make first calls against the public Preview sandbox. Credentials arrive the same day. Testing a provider app also needs a Preview tablespace from an athenaOne customer or the Marketplace Partner Program, so that date depends on them.

Working credentials, a first read and a scope list.
02

Tech Spec

We write the use cases, endpoints, scopes and data flows athenahealth asks for, from the code we are building, so the document matches what will run.

A submitted Tech Spec your team has reviewed.
03

Solution Validation

We walk athenahealth's integration design review with you, demonstrate each workflow and fix what they flag. New endpoints added later go through validation again.

Validated endpoints and a Go-Live authorization.
04

Customer enablement

We prepare the steps each practice follows to enable your app, then check department, provider and appointment reason setup practice by practice.

A repeatable onboarding runbook and support handover.

Evidence

The engineering we bring to athenahealth.

The engineering behind our athenahealth delivery, with public code and test results you can inspect.

Multi-EHR SMART on FHIR app

One app run against the Epic and Oracle Health developer sandboxes in a single session: the same launch, PKCE, token and context handling an athenahealth SMART app needs, with vendor differences kept in configuration.

Our own athenahealth Preview apps

In September 2026 we registered a 2-legged back-end app, a 3-legged provider app and a 3-legged patient app in athenahealth's developer portal, so we know the console, the scope model and the EHR-launch testing path first hand.

Open-source headless EHR

Passes 47 of 47 ONC (g)(10) SMART App Launch tests (11 Jun 2026), so we know the server side of the launch our apps depend on.

Headless EHR on GitHub ↗

Open-source SMART SDK

Our SMART on FHIR SDK on npm ships an athenahealth provider configuration alongside Epic and Cerner, so vendor differences live in configuration rather than in your application code.

@nirmiteeio/fhir-sdk on npm ↗

Where it starts

athenahealth developer portal, API documentation and sandbox.

Four places decide how an athenahealth integration starts. We work in all four with you, and our guides cover each at endpoint level.

athenahealth Developer Portal

Where your team signs in (Okta, at myidentity.platform.athenahealth.com) and registers apps in the Developer Console. Each app is one type: 2-legged, 3-legged patient or 3-legged provider. athenaPractice and athenaFlow use a separate portal, so we confirm which athenahealth product your customers run first.

Developer portal walkthrough →

athenahealth API documentation

docs.athenahealth.com holds the reference for both API families: the certified FHIR R4 API and the athenaOne APIs (more than 800 endpoints per athenahealth). We turn the pages that apply to your product into an endpoint and scope list before any build starts.

athenahealth API compared with Epic and Oracle →

Preview sandbox

A new app reaches the shared Preview practices 195900 and 1128700 the same day, at api.preview.platform.athenahealth.com. Patient apps and back-end reads can be proven there. Provider SMART apps and bulk export need a Preview tablespace from a customer or the Marketplace Partner Program.

Bulk FHIR export by vendor →

athenahealth Marketplace

The Marketplace is athenahealth's catalogue of third-party apps for athenaOne practices. A listing comes through the Marketplace Partner Program, which your company joins and holds. We build the integration and the evidence the program asks for, so the listing and the partner relationship stay yours.

Mirth and athenahealth workflows →

Before you commit

athenahealth Integration Questions, Answered.

Who holds the athenahealth agreement and API access?

You do, or your customer does. API access and any Platform Services contract sit with your organization, so the integration and its credentials stay yours. We build the integration, prepare the Tech Spec and validation evidence with you, and run the rollout through practice enablement.

Do we need the FHIR API, the athenaOne APIs or both?

Usually both. The certified FHIR R4 API is the right place to read clinical data. Booking appointments, posting documents, registering patients and change feeds run on athenaOne APIs, which need an athenahealth Platform Services contract. We map each screen and job in your product to one of the two before you commit.

How quickly can we start?

The same day. We register a Preview app in athenahealth's developer portal and make first calls against the public sandbox practice. Patient apps can be tested end to end there. Provider apps and bulk export need a Preview tablespace from a customer or the partner program, and we start that request in the first week.

Can we write data back into athenaOne?

Yes, for the workflows athenahealth supports, through athenaOne APIs: appointments with reason IDs, clinical documents to the chart, encounter documentation and patient updates. FHIR write scopes are not granted by default. We confirm each write, how it appears to clinicians and how duplicates are handled before it goes into scope.

Can you connect more than one practice?

Yes. Each practice enables your app and has its own departments, providers and appointment reasons. We keep that per-practice context in configuration, not code, and give you an onboarding runbook so every new practice follows the same checklist.

Do we still need an integration if we use CommonWell, Carequality or TEFCA?

Often, yes. athenaOne reaches TEFCA through CommonWell Health Alliance, a designated QHIN, and exchanges records through CommonWell and Carequality. That network exchange is good for retrieving records for treatment. It does not put your product inside the athenaOne workflow, book appointments or write back to the chart; those need the APIs.

Where is the athenahealth developer portal?

athenaOne developers sign in to the athenahealth Developer Portal and manage apps in its Developer Console. Registering an app gives you Preview credentials the same day. athenaPractice and athenaFlow have a separate developer portal, with its own accounts and sandboxes, so the product your customers run decides which portal you need.

Where is the athenahealth API documentation?

At docs.athenahealth.com. It covers the certified FHIR R4 API, the athenaOne API reference, authorization, Event Notifications and onboarding guides. The live FHIR CapabilityStatement at api.platform.athenahealth.com/fhir/r4/metadata is the quickest check of what the FHIR API allows: on 17 October 2026 it listed 32 resource types, and QuestionnaireResponse was the only one that allowed create.

Is there an athenahealth sandbox for testing?

Yes. Every new athenaOne app can call the shared Preview practices 195900 and 1128700 at api.preview.platform.athenahealth.com, with lower limits than production (15 requests per second and 50,000 per day). Patient apps and back-end reads can be tested there end to end. Provider apps that launch inside athenaOne need a Preview tablespace from a customer or the Marketplace Partner Program.

What are the athenaOne APIs?

The athenaOne APIs are athenahealth's proprietary REST APIs under /v1/{practiceid}/, where scheduling, chart write-back, documents, patient registration, billing and changed-data feeds live. They sit alongside the certified FHIR R4 API, need an athenahealth Platform Services contract, a Tech Spec and Solution Validation, and are billed by call volume.

How do we get listed on the athenahealth Marketplace?

Through athenahealth's Marketplace Partner Program, which your company applies to and holds. The program also gives partners a dedicated Preview tablespace for testing provider apps. We build and validate the integration with you and prepare the technical material the program reviews; the listing decision is athenahealth's.

How long does an athenahealth integration take?

In our estimates, 6 to 10 weeks for a certified read-only app to reach its first practice, and 3 to 6 months for an integration that writes through the athenaOne APIs. The access path sets most of that calendar: the Platform Services contract, the Tech Spec, Solution Validation and each practice enabling your app. We start those on day one and build in parallel.

What drives the cost of athenahealth integration services?

Our engineering cost grows with the number of workflows, whether you write back or only read, the app types you need (patient, provider, back-end), Event Notifications or HL7 v2 interfaces, and how many practices you roll out to. athenahealth's own charges are separate: certified FHIR APIs are free to call, and athenaOne API usage is metered under your contract.

What Affects Cost and Timing?

The number of workflows, read versus write scope, whether you need Event Notifications or HL7 v2, and how fast you get a Preview tablespace and a Platform Services contract. Certified FHIR APIs cost nothing to call; athenaOne APIs are metered by call volume at a rate athenahealth agrees with you. Those charges are separate from our engineering fees.

Define the next step

What does your product need to do inside the practice?

Tell us about your product, the practices you sell to and the outcome you need. We will come back with the app types, API surfaces and access steps your workflow needs.

  • The target customer and athenahealth product
  • Any Preview app, contract or customer sponsor you already have
  • Your workflow and delivery priorities

Please don’t include patient data, credentials or sensitive records.

Please exclude patient data and credentials. We use these details to respond to your enquiry. Privacy policy

Thank you. Your enquiry has been received. Our team will review your requirements.

athenahealth and athenaOne are trademarks of athenahealth, Inc. Other product names are trademarks of their respective owners.

From our YouTube channel

Related videos

Explore the workflows and decisions behind this service. Demonstrations and recorded discussions have the scope described in each video.