# athenaOne Document Upload Research ## Date: 2026-03-16 ## Context Kinometric needs to upload PDF balance test results to patient charts in athenaOne. Current sandbox integration uses `POST /patients/{id}/documents/clinicaldocument` (proprietary API). This research investigates whether that endpoint requires a paid Platform Services contract and what alternatives exist. --- ## 1. athenahealth API Tiers athenahealth has **two distinct API tiers**: ### Certified FHIR APIs (Free) - **Cost**: No cost to customers and partners - **Purpose**: ONC 21st Century Cures Act compliance (g)(10) criterion - **Scope**: **READ-ONLY** — designed for PHR (Personal Health Record) apps to access EHI (Electronic Health Information) - **Standard**: HL7 FHIR R4, USCDI data elements - **Production access**: Self-service — no Platform Services contract needed - **Key limitation**: No write operations. The ONC g(10) mandate explicitly requires only read access - **Resources**: Patient, AllergyIntolerance, CarePlan, CareTeam, Condition, Device, DiagnosticReport, DocumentReference (READ), Encounter, Goal, Immunization, Location, MedicationRequest, Observation, Organization, Practitioner, Procedure ### Proprietary APIs (Paid — Platform Services) - **Cost**: Requires **athenahealth Platform Services contract** (custom pricing, not publicly disclosed) - **Purpose**: Full read/write integration with athenaOne workflows - **Scope**: 800+ endpoints including **write operations** across administrative, clinical, and financial functions - **Production access**: Requires Platform Services contract for production OAuth credentials - **Includes**: `POST /patients/{id}/documents/clinicaldocument` and all other write endpoints ### Bottom Line **The `clinicaldocument` POST endpoint is a proprietary API that requires a paid Platform Services contract for production use.** The free Certified APIs are read-only and cannot upload documents. --- ## 2. FHIR DocumentReference — Can It Upload? ### athenaPractice/athenaFlex (NOT athenaOne) - The `mydata.athenahealth.com` FHIR server (used by athenaPractice and athenaFlow) **does support** DocumentReference create (POST) - Endpoint: `POST [base]/fhir/DocumentReference` - Supports PDF attachments via FHIR Attachment datatype - Returns 201 on success ### athenaOne - athenaOne's Certified FHIR APIs support DocumentReference for **read/search only** - The Certified tier does NOT include write operations - Write operations on athenaOne go through the proprietary API (Platform Services required) ### Verdict **FHIR DocumentReference POST is available for athenaPractice/athenaFlex but NOT for athenaOne free tier.** For athenaOne, document upload still requires the proprietary API. --- ## 3. Direct Messaging (Direct Protocol) ### What It Is - Secure encrypted email using the Direct standard (required for Meaningful Use) - Used to send Summary of Care Records (C-CDA documents) between providers - Receiving athenaClinicals classifies inbound Direct messages as `ClinicalDocument_CCDA` and routes to Clinical Inbox ### Can It Upload Custom PDFs? - Direct messaging is designed for **C-CDA documents** (Continuity of Care), not arbitrary PDFs - Documents arrive as CCDs, not as custom clinical documents attached to specific patients - Requires a Direct address (contains `@direct`) for the receiving provider - Would need to be processed/matched to the right patient chart by the receiving practice ### Automation Feasibility - Could potentially send C-CDA wrapped documents via Direct protocol - Documents land in Clinical Inbox for manual review/routing, not auto-filed to patient charts - athenahealth provides Direct addresses to all athenaClinicals clients ### Verdict **Technically possible but impractical** for automated PDF uploads. Direct is designed for C-CDA care summaries between providers, not for attaching custom test result PDFs to specific patient charts. Documents would require manual staff intervention to route to the correct patient. --- ## 4. Third-Party Integration Platforms ### Redox - Acts as middleware between apps and EHRs (including athenahealth) - Supports document upload via normalized JSON API → translates to target EHR format - Handles FHIR, HL7v2, CCDA, CSV - **But**: Redox still needs to call athenahealth's proprietary API on the backend — doesn't bypass the Platform Services requirement - **Pricing**: Custom (Platform Fee + Volume Tier), not publicly disclosed - **Adds**: complexity and another vendor relationship ### Health Gorilla - Health Information Exchange (HIE) network - Focuses on data retrieval and aggregation from provider networks - Connected to Carequality and CommonWell - **Not primarily a write/upload platform** — more for pulling records ### Metriport - Open-source Medical API, listed on athenahealth Marketplace - Connects to CommonWell and Carequality (300M+ patient records) - Has document upload capability - Has a free sandbox tier - **But**: Their athenaOne integration focuses on **reading** medical record summaries, not writing documents to charts - Would still need athenahealth's write API access ### Qvera (Interface Engine) - HL7 interface engine supporting athenahealth integration - Can transform and route HL7 messages, FHIR, CDA - Handles ADT/SIU/ORU message types - **Could be used to send HL7v2 results** but requires an established HL7 interface with the practice ### Verdict **Third-party platforms don't bypass the Platform Services requirement.** They simplify the integration work but ultimately still need write access to athenaOne, which requires the same contract. They add cost and complexity. --- ## 5. HL7 v2 Messages (MDM/ORU) ### athenahealth HL7v2 Support - Supports inbound **ORU** messages (R01, R03) for clinical results, lab results, and imaging results - Uses HL7 v2.3.1 format - Connectivity: TCP/IP socket with SSH or VPN - Dedicated documentation at `docs.athenahealth.com/interfaces/guides/hl7v2-documents` ### MDM Messages - MDM (Medical Document Management) messages are a standard HL7v2 way to push documents - MDM_T02 (original document notification and content) can include PDF content (base64 encoded in OBX segments) - **athenahealth's documented interfaces focus on ORU, not MDM** — unclear if MDM is supported ### Setup Process - Requires a formal interface project with athenahealth - Kick-off call, scoping, testing - Typically used by labs, imaging centers, reference labs - **Requires the practice to have an active HL7 interface** (usually part of their athenaOne service, but configuration work is required) ### Verdict **HL7v2 ORU is a real option** if Kinometric can be set up as a "results sender" (like a diagnostic lab or testing device). The practice would need to configure an inbound interface. This bypasses the API/Platform Services requirement but introduces infrastructure complexity (TCP/IP socket, VPN/SSH, HL7 message formatting). May require athenahealth interface setup fees. --- ## 6. Fax-to-Chart Workflow ### How It Works - athenaOne uses **athenaFax** (powered by eFax Corporate) for cloud-based faxing - Inbound faxes are automatically scanned, patient-matched, and routed to the correct chart - AI-powered labeling identifies document type and assigns to correct patient/provider - Documents land in Clinical Inbox for staff review ### Automation Potential - Could use a **cloud fax API** (eFax, RingCentral, Twilio Fax) to programmatically send a fax to the practice's fax number - athenaOne would receive and auto-route to the patient chart - Include patient name, DOB, and identifiers on the fax cover page for matching - The PDF would need to be clearly formatted for OCR/matching ### Pros - **No athenahealth API contract needed** — uses existing fax infrastructure - Practice already has fax number and fax-to-chart routing - HIPAA-compliant when using certified fax providers - Low technical complexity ### Cons - Requires manual staff review to confirm routing - Fax quality may degrade the PDF - Not real-time — could take minutes to hours - Patient matching may fail if identifiers are unclear - Not a "clean" integration — feels manual/legacy - Cloud fax API costs (~$0.05-$0.10 per page) ### Verdict **Viable as a low-cost workaround**, especially for practices that already rely on fax workflows. Not ideal for a polished product experience. Could serve as an interim solution while negotiating Platform Services access. --- ## 7. CCDA/CCD Document Exchange ### What athenahealth Supports - athenahealth is MU3 certified for CCDA export - Supports both PDF and XML versions of health records - `$docref` operation produces a CCD for the most recent encounter - `$convert-cda` constructs a CDA document from referenced content ### For Importing/Uploading - C-CDA import is primarily through **Direct messaging** (see section 3) or **data conversion services** - athenahealth's data conversion tools are for migrating data from other EHRs, not for routine document submission - C-CDA documents received via Direct land as `ClinicalDocument_CCDA` in Clinical Inbox ### Can Kinometric Use This? - Would need to wrap the PDF test results in a C-CDA envelope - Send via Direct protocol to the practice's Direct address - Document would arrive in Clinical Inbox as a C-CDA - Staff would need to review and file it ### Verdict **Not practical for PDF test result uploads.** C-CDA is designed for structured clinical data exchange (medications, problems, allergies), not for attaching custom PDF reports. The overhead of wrapping a PDF in C-CDA, sending via Direct, and then having staff manually route it makes this approach unsuitable. --- ## 8. Recommended Strategy ### Short Term (Now) 1. **Confirm with athenahealth** whether `POST /clinicaldocument` requires Platform Services. Contact their developer support directly — it's possible the endpoint is available at the Marketplace tier without a full Platform Services contract. 2. **Apply for the Marketplace Partner Program** — no fees to join or list an app. Once listed, you may get production API access for your integration use case. 3. **Test the fax workaround** as an interim fallback — programmatic fax of PDF results to the practice's athenaFax number. ### Medium Term 4. **Explore HL7v2 ORU interface** if the practice is willing to set up an inbound results interface. Kinometric would act as a "diagnostic results sender" sending test results via ORU messages over TCP/IP. 5. **Contact athenahealth Partnership team** at Marketplace@athenahealth.com to discuss pricing for Platform Services. Explain the use case (medical device/diagnostic results upload). ### Key Insight The athenahealth Marketplace program states: **"There is no fee to use the Marketplace, and athenahealth does not charge interface or setup fees to integrate solutions."** This suggests that becoming a Marketplace partner may provide access to the proprietary APIs needed for document upload without a separate Platform Services fee. This is the most promising avenue to investigate. --- ## Sources - [athenahealth Certified APIs Guide](https://docs.athenahealth.com/api/guides/certified-apis) - [athenahealth API Overview](https://docs.athenahealth.com/api/guides/overview) - [athenahealth Onboarding Overview](https://docs.athenahealth.com/api/guides/onboarding-overview) - [athenahealth Developer Portal](https://www.athenahealth.com/developer-portal) - [Clinical Document API Reference](https://docs.athenahealth.com/api/api-ref/document-type-clinical-document) - [FHIR DocumentReference (athenaOne)](https://docs.athenahealth.com/api/fhir-r4/document-reference) - [FHIR DocumentReference (athenaPractice)](https://mydata.athenahealth.com/static/apidoc/ig-ge-documentreference.html) - [Self-Service Onboarding for Certified-Only Apps](https://docs.athenahealth.com/api/resources/233-release-developer-console-allows-self-service-onboarding-all-apps-using-only) - [Certified API Access](https://docs.athenahealth.com/api/resources/certified-api-access) - [athenahealth Marketplace Program](https://www.athenahealth.com/solutions/marketplace-program) - [athenahealth Marketplace Partners](https://www.athenahealth.com/solutions/marketplace-partners) - [HL7v2 Documents Interface Guide](https://docs.athenahealth.com/interfaces/guides/hl7v2-documents) - [HL7 Clinical Results Implementation Guide (PDF)](https://www.athenahealth.com/~/media/athenaweb/files/developer-portal/clinical_results_interface_implementation_guide.pdf) - [Direct Messaging in athenaClinicals](https://docs.athenahealth.com/downloads/direct-datasheet) - [athenaFax / eFax Integration](https://www.efax.com/partners/athenahealth) - [ONC g(10) Criterion](https://onc-healthit.github.io/api-resource-guide/g10-criterion/) - [Redox Platform](https://redoxengine.com) - [Metriport athenahealth Integration](https://www.metriport.com/athenahealth-integration) - [Qvera athenahealth Solutions](https://www.qvera.com/athenahealth-solutions/) - [GitHub: DocumentReference Upload Issue #149](https://github.com/athenahealth/apiserver-athenaFlex/issues/149) - [Go athenahealth SDK (document endpoints)](https://pkg.go.dev/github.com/eleanorhealth/go-athenahealth/athenahealth)