athenahealth Integration Guide: MDP Marketplace, REST & FHIR

athenahealth is the largest cloud-native EHR vendor in US ambulatory care. Tens of thousands of provider practices — solo physicians, multi-specialty groups, community health centers, and regional health systems — run their clinical and billing workflows on athenaOne, athenahealth's integrated product suite. For any healthtech product aimed at ambulatory medicine, an athenahealth integration is usually an early roadmap item.

The good news: athena is technically friendlier to integrate with than legacy on-prem EHRs. Its cloud-native architecture means a single, well-documented API surface shared across every customer, no version fragmentation, and predictable behavior in sandbox. The less-good news: the auth model is practice-scoped, HL7 v2 feeds aren't self-service, MDP certification has its own timeline, and throttling is strictly enforced at scale.

This guide walks through how an athenahealth integration actually gets shipped in 2026 — from MDP onboarding through sandbox build through first-practice go-live. If you want hands-on help, our EHR integration services team has delivered athena projects across the ambulatory care space.

1. The athenahealth Stack in 2026

The primary integration layers you'll touch:

athenaNet — the cloud platform running the EHR, PM, and ancillary services.
athenaOne — the unified product branding (athenaCollector + athenaClinicals + athenaCommunicator) that most customers subscribe to.
athenaNet API — the proprietary REST API surface. Covers billing, scheduling, patient management, and operational workflows.
FHIR R4 API — the standards-based clinical API surface, SMART-launched and OAuth-authorized.
HL7 v2 connectors — arranged through athena's Interface team for event-driven real-time integrations (ADT, ORU, VXU, etc.).
More Disruption Please (MDP) — athenahealth's developer program and marketplace for third-party apps.
athenaOne Mobile — clinician-facing mobile app where SMART-launched apps can appear.

For a broader view on picking integration partners and approaches, see our EHR integration guide and healthcare interoperability guide.

2. athenaCollector, Clinicals, and Communicator

Understanding what the customer actually has subscribed to is critical — integration scopes depend on it.

athenaCollector — practice management and revenue-cycle. Scheduling, patient registration, insurance and eligibility, claims, patient statements, payment posting. Customer can use athenaCollector without athenaClinicals if they have a different EHR.
athenaClinicals — the EHR. Clinical documentation, problem list, medications, order management, results review, e-prescribing. FHIR clinical resources come from athenaClinicals.
athenaCommunicator — patient portal, secure messaging, appointment reminders, online scheduling.
Population Health — separate offerings for care management, quality reporting, and risk adjustment across populations.

A billing-focused integration (charges, claims, payments) only needs athenaCollector access. A clinical integration (medications, labs, problems) needs athenaClinicals. A scheduling app may need both plus Communicator. Always scope per-customer what they actually have.

3. More Disruption Please (MDP) Marketplace

More Disruption Please (MDP) is athenahealth's partner program and marketplace. It's the gateway for third-party vendors to get sandbox access, documented APIs, OAuth clients, a listing, and a path to be enabled at customer practices.

What MDP gives you

Sandbox access — a non-production athenaNet instance with synthetic data.
Documented APIs — athenaNet REST API and FHIR R4 API references.
OAuth client registration — credentials for authenticating to athena APIs.
Certification testing — a structured validation process for your integration before it's listed.
Marketplace listing — discoverability by athena customer practices.
Partner support channels — a partner manager and technical contacts at athenahealth.

Tier structure

Like other EHR marketplaces, MDP has tiers with different API access levels, certification requirements, and commercial terms. Read-only apps typically sit in lower tiers; write-back and clinical workflow apps require higher tiers with deeper security review. Current tier names and pricing evolve; treat the MDP portal as the source of truth.

Per-practice onboarding

Critically, a marketplace listing does not automatically enable your app at any specific customer practice. Each practice must explicitly enable your integration in their athenaNet administrative settings, after which your OAuth client receives a practice context (practice ID) and the integration can begin operating. Plan for this per-practice onboarding step in your go-to-market model.

4. athenaNet API — REST Endpoints

The athenaNet API is athenahealth's proprietary REST surface, distinct from the FHIR API. It covers workflows that FHIR doesn't represent well (billing, claims, scheduling operations) and provides more granular access to athena's internal data model for write operations.

Categories you'll touch most:

Patient — demographics, registration, insurance, contact preferences
Appointment — slot search, booking, reschedule, cancel
Encounter and Chart — visit notes, chart summary, problem list
Clinical Document (CCD) — structured clinical summary export
Lab and Imaging Order — order submission and status retrieval
Lab Results — result pull with disposition and filing workflow
Medications — active medications, prescribe, refill request
Billing and Claims — charges, claims, payments, patient balances
Insurance Package — eligibility checks and coverage retrieval

Authentication

athenaNet uses OAuth 2.0 client credentials for server-to-server flows. A typical token exchange:

POST https://api.athenahealth.com/oauth2/v1/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)

grant_type=client_credentials&
scope=athena/service/Athenanet.MDP.*

HTTP/1.1 200 OK
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "athena/service/Athenanet.MDP.*"
}

Example: get patient

GET https://api.athenahealth.com/v1/PRACTICE_ID/patients/1234
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

HTTP/1.1 200 OK
[
  {
    "patientid": "1234",
    "firstname": "MARIA",
    "lastname": "GARCIA",
    "dob": "06/12/1978",
    "sex": "F",
    "primarydepartmentid": "101",
    "primaryproviderid": "11",
    "status": "active",
    "homephone": "303-555-0199",
    "email": "maria.garcia@example.com"
  }
]

Example: book appointment

POST https://api.athenahealth.com/v1/PRACTICE_ID/appointments/APPOINTMENT_ID
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/x-www-form-urlencoded

patientid=1234&
appointmenttypeid=82&
departmentid=101&
reasonid=558

HTTP/1.1 200 OK
[
  {
    "success": true,
    "appointmentid": "56789"
  }
]

Notice the PRACTICE_ID in the URL path — every athenaNet API call is practice-scoped. Your OAuth client has access to one or more practice IDs based on which customer practices have enabled your integration.

5. athenahealth FHIR R4 API and Bulk Data

athenahealth's FHIR R4 API is US Core compliant and covers the clinical-data resources most third-party apps need. It supports SMART on FHIR launch contexts (EHR launch and standalone launch) and the Bulk Data Access specification for population-level exports.

Resources available:

Patient — US Core-compliant patient demographics and identifiers
Encounter — outpatient and inpatient encounter context
Observation — vitals, lab results, social history
Condition — problem list entries with SNOMED and ICD-10 codes
MedicationRequest — active prescriptions and orders
AllergyIntolerance — patient allergy list
Procedure — completed procedures with CPT and SNOMED codes
DiagnosticReport — lab and imaging reports
DocumentReference — structured documents including CCDs
Bulk Data ($export) — population-level ndjson exports

SMART configuration discovery

GET https://api.athenahealth.com/fhir/r4/.well-known/smart-configuration

{
  "authorization_endpoint": "https://api.athenahealth.com/oauth2/v1/authorize",
  "token_endpoint": "https://api.athenahealth.com/oauth2/v1/token",
  "scopes_supported": [
    "launch",
    "launch/patient",
    "patient/Patient.read",
    "patient/Observation.read",
    "user/*.read",
    "system/*.read",
    "offline_access",
    "openid",
    "fhirUser"
  ],
  "response_types_supported": ["code"],
  "capabilities": [
    "launch-ehr",
    "launch-standalone",
    "client-confidential-symmetric",
    "client-confidential-asymmetric",
    "permission-patient",
    "permission-user",
    "sso-openid-connect"
  ]
}

A typical FHIR read

GET https://api.athenahealth.com/fhir/r4/Patient/a-1234
Authorization: Bearer ACCESS_TOKEN
Accept: application/fhir+json

HTTP/1.1 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "Patient",
  "id": "a-1234",
  "identifier": [
    { "system": "http://athenahealth.com/identifier", "value": "1234" }
  ],
  "name": [
    { "use": "official", "family": "Garcia", "given": ["Maria"] }
  ],
  "gender": "female",
  "birthDate": "1978-06-12",
  "address": [
    { "use": "home", "city": "Denver", "state": "CO", "postalCode": "80203" }
  ]
}

Bulk Data $export

GET https://api.athenahealth.com/fhir/r4/Group/GROUP_ID/$export
Authorization: Bearer SYSTEM_ACCESS_TOKEN
Accept: application/fhir+json
Prefer: respond-async

HTTP/1.1 202 Accepted
Content-Location: https://api.athenahealth.com/fhir/r4/bulkdata/JOB_ID

# Poll Content-Location until complete, then retrieve ndjson file list:
{
  "transactionTime": "2026-04-21T09:30:00Z",
  "requiresAccessToken": true,
  "output": [
    { "type": "Patient", "url": "https://.../Patient-1.ndjson" },
    { "type": "Condition", "url": "https://.../Condition-1.ndjson" },
    { "type": "Observation", "url": "https://.../Observation-1.ndjson" }
  ]
}

See our FHIR integration guide for the fundamentals of FHIR integration patterns.

6. HL7 v2 Connectors and Transports

athenahealth supports HL7 v2 interfaces for event-driven integrations that the REST/FHIR APIs don't cover well — real-time ADT streams, lab result pushes, immunization registry updates, and more. These are arranged through athena's Interface team, typically as part of a customer onboarding project.

Common HL7 v2 patterns

Outbound ADT. athena sends ADT A01/A03/A04/A08 on admit/discharge/registration events.
Inbound ORU. Lab results from reference labs flow into athena as ORU messages for filing into the chart.
Outbound ORM. Lab and imaging orders leave athena to ancillary systems.
Outbound VXU. Immunization data flows to state registries.
Inbound SIU. Scheduling events from integrated scheduling systems can flow into athena.

Transport options

athena's Interface team typically offers MLLP (MLLPS preferred), SFTP, and HTTPS for HL7 v2 exchange. For real-time bidirectional workflows MLLPS is standard. For batch flows (daily file drops, historical result loads) SFTP is common. The specific transport is agreed during interface setup.

A typical athena ADT

MSH|^~\&|ATHENA|MCGOWAN_FAMILY_PRACTICE|VENDOR|VENDOR_CORP|20260421093000||ADT^A04|MSG01234|P|2.5.1
EVN|A04|20260421093000
PID|1||44556677^^^ATHENA^MR||GARCIA^MARIA||19780612|F|||45 ELM ST^^DENVER^CO^80203
PV1|1|O|PRIMARY_CARE^EXAM1^A|EL|||55^CHAN^WEI^MD|||FAM|||||||55^CHAN^WEI^MD|OUT|VN112233|SELF

For HL7 v2 fundamentals and troubleshooting, see our HL7 integration guide and MLLP connection refused troubleshooting.

7. How Bidirectional Sync Actually Works

Bidirectional sync — your platform and athena both having current, consistent data — is a common requirement and a common pitfall. A realistic architecture:

Event-driven inbound. athena pushes ADT/ORU via HL7 v2 to your edge (often a Mirth Connect listener). This gives near real-time visibility into patient registration, encounters, and results.
Periodic polling inbound. For resources not in the HL7 v2 stream (updated medications, problems, appointments), poll the athenaNet or FHIR API on a schedule. Use If-Modified-Since or resource-specific timestamps to limit fetches.
Event-driven outbound. Changes in your platform that should reflect in athena (new appointment booking, e-prescribe order, patient update) go out as REST calls with the practice-scoped OAuth token.
Reconciliation. A daily or hourly job that compares expected state between the two systems and flags drift. Essential for any integration with write operations.
Idempotency keys. Use externally-generated IDs or custom fields so duplicate writes don't create duplicate records.

Why Mirth Connect fits here

Mirth Connect is a natural fit on the vendor side: it terminates HL7 v2 from athena, translates to FHIR or a vendor-internal model, persists and retries, calls athena REST/FHIR endpoints via HTTP Sender, and manages reconciliation jobs. See the Mirth Connect guide and Mirth support and HL7 integration services.

8. Cloud-Native Advantages and Constraints

athenahealth's single-version cloud architecture shapes the integration experience in ways that matter:

Advantages

One version. Your integration behaves the same at every customer practice — no version-drift surprises.
Consistent endpoints. The base URL and API versioning are stable across customers; per-practice differences live only in the practice ID and enabled scopes.
New features reach every practice at once. athena can't ship a feature to some customers and not others the way on-prem EHRs can fragment.
Predictable sandbox. The MDP sandbox behaves like production for the APIs it covers — fewer "works in sandbox, breaks in prod" incidents than competitors.

Constraints

Less per-customer customization. You can't get a customer to expose a custom data element through a custom API endpoint — the data model is what it is.
Shared throttling. athena enforces rate limits across all clients at a practice. A noisy other integration can tighten the ceiling for you.
Release-coupled changes. Fixes or new features land on athena's schedule, not yours. Plan for feature requests to take quarters, not weeks.
Sandbox data variation. Synthetic sandbox data may not exercise every edge case; budget for real-practice testing during the first customer go-live.

9. Sandbox Access and Certification

After joining MDP, you receive sandbox credentials and access to a non-production athenaNet environment. The sandbox is shared (multiple MDP partners use it), so don't rely on specific record state persisting beyond your test runs.

Sandbox workflow

MDP approves your sandbox request; you receive an OAuth client ID and secret.
Sandbox base URL: https://api.preview.platform.athenahealth.com (exact URL per the MDP portal).
Test practice IDs are provided — build and test against these.
Complete certification testing — a scripted run-through of required API calls with expected responses.
Security review and listing prep; MDP marketplace listing goes live.

Certification

MDP certification validates that your integration uses APIs correctly — pagination, error handling, OAuth token refresh, practice-scoped calls. It's not as heavyweight as ONC certification but it's a real gate, and first-time attempts often fail on edge cases. Budget two to four weeks for certification rather than assuming a single pass.

10. Realistic Implementation Timelines

A typical mid-complexity athenahealth integration timeline:

✓Weeks 0–2: MDP marketplace interest, NDA, scoping call with athena partner team
✓Weeks 2–5: Sandbox credentials provisioned, first authenticated API call
✓Weeks 5–12: Build core flows against sandbox, mock HL7 feed if needed
✓Weeks 12–18: MDP certification testing, security review, listing prep
✓Weeks 18–24: Per-customer (practice) onboarding — credentials, endpoint URLs, HL7 setup
✓Weeks 24–32: Pilot practice go-live, hypercare, scale-out to additional customers

Once the first practice is live, subsequent practice onboardings are typically 2–4 weeks each — much faster than the initial MDP build. For broader planning context, see our EHR integration project timeline and EHR integration cost guide 2026.

11. Common Pitfalls on athena Projects

Treating the athenaNet API and the FHIR API as interchangeable — they cover different surfaces and have different auth and rate-limit models
Assuming athena's sandbox data matches production shape — sandbox has synthetic data with different IDs and often narrower content
Overlooking practice-scoped credentials — each customer practice has its own API context and must be onboarded individually
Forgetting that HL7 v2 interfaces on athena are generally arranged through athena's Interface team, not self-service
Missing the distinction between athenaCollector (billing) and athenaClinicals (clinical) scopes when selecting API access
Assuming write-back is freely available — most write operations require MDP partnership tier and explicit scope approval
Underestimating throttling — athena's APIs enforce per-practice rate limits; integrations that don't paginate and back off will fail at scale

For choosing a partner who has navigated these, see how to choose an EHR integration partner.

12. Frequently Asked Questions

What is athenahealth?

athenahealth is a cloud-based health IT platform that provides EHR, practice management, revenue-cycle, and patient-engagement services primarily to ambulatory (outpatient) medical practices and health systems. Unlike Epic or Cerner, athenahealth is multi-tenant cloud-native — every customer runs on shared infrastructure with logically separated data, and athenahealth maintains a single application version across all customers.

What's the difference between athenaCollector and athenaClinicals?

athenaCollector is the practice-management and revenue-cycle product — scheduling, billing, claims, patient statements. athenaClinicals is the EHR product — clinical documentation, e-prescribing, order management, chart. Many practices run both; some only run athenaCollector and use a different EHR. When scoping an integration, confirm which product the customer actually uses — FHIR clinical data requires athenaClinicals.

What is More Disruption Please (MDP)?

More Disruption Please is athenahealth's developer and partner program — the equivalent of Epic's Showroom or Cerner's Code program. It provides sandbox access, API documentation, certification testing, and marketplace listing. MDP membership is practically required for commercial third-party apps; ad-hoc integrations at a single customer practice are harder but possible through that practice's administrative settings.

Does athenahealth support FHIR?

Yes. athenahealth exposes a FHIR R4 API covering US Core resources plus additional data via their proprietary athenaNet API. They support SMART on FHIR EHR-launch and standalone-launch flows, and Bulk Data $export for population-level exports. Customer practices must have FHIR enabled on their account; in 2026 this is the default for US Core compliance, but older or special-configuration practices may need it turned on.

Can Mirth Connect integrate with athenahealth?

Yes — most commonly in three ways. Mirth can terminate inbound HL7 v2 feeds from athena's Interface team (ADT, ORU, VXU). Mirth can make outbound HTTP calls to athenaNet REST endpoints and FHIR endpoints using OAuth-authenticated HTTP Sender. And Mirth can serve as the normalization layer between athena's data and your internal data model. Many vendor-side athena integrations we see use Mirth as the central edge.

What is athenaNet?

athenaNet is athenahealth's multi-tenant cloud platform — the software running the EHR, PM, and ancillary modules. The 'athenaNet API' refers to the REST-based proprietary API surface for accessing athenaNet data, distinct from the FHIR API. athenaNet API covers billing, claims, scheduling, and operational workflows that aren't fully represented in FHIR.

Does athena support real-time HL7 v2?

Yes — athena provides HL7 v2 connectors for ADT, ORU (lab results and radiology), VXU (vaccinations), and other common messages, typically via secure transport arranged through athena's Interface team. These are not self-service; each HL7 interface is provisioned as part of a customer onboarding project with lead times measured in weeks.

How does cloud-native architecture affect integration?

Cloud-native means every athena customer runs on the same software version — no multi-version fragmentation like you see with on-prem EHRs. API behavior is more consistent across customers, and new capabilities reach every practice at once. The trade-off is less customer-specific customization; athena's data model is what it is, and individual practices can't expose proprietary extensions as easily as Epic or Cerner customers can.

How long does an athenahealth integration take?

A typical integration from MDP interest to first practice go-live runs 4–8 months. Read-only FHIR apps can go faster (2–4 months). Bidirectional clinical integrations with HL7 v2 interfaces and MDP certification tend to land at 6–9 months. After the first practice is live, additional practice onboardings are much faster — weeks, not months.

athenahealth Integration Guide:MDP, athenaNet API, and FHIR

Table of Contents