athenahealth API notes: Preview, practice access and claims
You want to read claims from an athenahealth practice and you have no contract with anyone yet. athenahealth lets you start anyway. A developer account gets Preview credentials and a shared sandbox practice on the first day. Production is a different matter, and the pages below describe the gap.
Three API families
The documentation overview separates the offer into athenaOne APIs, FHIR APIs and Certified APIs. athenaOne APIs are proprietary REST endpoints with write support across administrative, clinical and financial functions. FHIR APIs expose USCDI clinical data in DSTU2 and R4. Certified APIs are the FHIR endpoints required by ONC certification, offered at no cost. Claims and money live in the athenaOne family.
The Preview environment
The environment URLs page gives two bases.
Preview: https://api.preview.platform.athenahealth.com
Production: https://api.platform.athenahealth.comCredentials are issued for one environment and work only there. The sandbox page states that every Preview user gets practice ID 195900 for ambulatory testing and 1128700 for hospital testing, and practice 80000 for personal health record apps. athenahealth also says it does not guarantee stable IP addresses and recommends against IP whitelisting on your side.
A list call in Preview looks like this: GET https://api.preview.platform.athenahealth.com/v1/195900/claims?createdstartdate=11/01/2026&createdenddate=11/08/2026
Getting a token
The token endpoint page documents POST /oauth2/v1/token. For a server-to-server app, which athenahealth calls 2-legged OAuth, the simplest form is basic auth with the client ID and secret.
curl https://api.preview.platform.athenahealth.com/oauth2/v1/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d "grant_type=client_credentials" \
-d "scope=athena/service/Athenanet.MDP.*"The page states that 2-legged apps are only compatible with the athena/service/MDP.* scope and system-level FHIR scopes. A client-assertion JWT is also supported, signed with a key you upload or host at a JWKS URL. The JWT needs aud set to the token URL of the environment, iss and sub set to the client ID, and an exp less than an hour out. The response is an access token with expires_in. The page gives 60 minutes as the default lifetime and shows 300 in its example. It also notes a common mistake: posting the client ID and secret as form fields fails. They go in the basic authorization header.
Practice-level access
The sandbox hides this part. The onboarding overview splits apps by API level at creation.
If your app uses only Certified APIs, Production credentials are granted on creation. But "an athenaOne customer must enable your application for their practice in their practice settings before your OAuth credentials may access data from the practice."
If your app uses one or more non-Certified APIs, which includes every claims endpoint, the page states that such apps "require an athenahealth Platform Services contract to be issued Production OAuth credentials". After that, a customer must request that your app be given access to their Production environment. Access to a customer's Preview or Production requires "the signed authorization and consent of the healthcare organization".
The contracting page names the routes in. A vendor that is not an athenaOne customer joins the Marketplace Partner Program. An existing customer contacts their Customer Success Manager. The process page adds the middle steps: a Tech Spec form reviewed with an athenahealth API consultant, a dedicated Preview environment, a Solution Validation demo, a Go-Live Authorization Form, then Production credentials. The pages do not state fees or timelines.
What RCM data is exposed
The Claim API reference documents these primary endpoints.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/{practiceid}/appointments/{appointmentid}/claim | Create a claim for a checked-in appointment |
| POST | /v1/{practiceid}/claims | Create a claim with no appointment |
| GET | /v1/{practiceid}/claims | List claims by date range, provider, department, payer, patient or procedure code |
| GET | /v1/{practiceid}/claims/{claimid} | One claim |
| PUT | /v1/{practiceid}/claims/{claimid} | Update allowables, custom fields and referral authorization |
| GET | /v1/{practiceid}/claims/{claimid}/claimtransactions | Charge lines with payments, adjustments and outstanding amount |
| GET | /v1/{practiceid}/patients/{patientid}/claims/patientoutstanding | Open claims for a patient |
| GET | /v1/{practiceid}/patients/{patientid}/claims/patientclosed | Closed claims for a patient |
| GET | /v1/{practiceid}/claims/changed | Claims changed since your last poll |
A claim record carries chargeamount, claimcreateddate, billedservicedate, diagnoses, procedures, primary, secondary and patient payer objects with status and notes, referral and provider IDs, and transactiondetails that sum to the charge amount. Each claim transaction exposes amount, payments, adjustments, outstandingamount, payer, procedurecode and lastbilleddate.
The reference states the limits on writes: one claim per call, no edit or delete after submission, and at most four diagnosis codes per procedure code. A create call requires a primary ICD-10 code on each charge. Claim creation for an appointment works only if the appointment has no claim yet and has been checked in.
The changed-claims subscription fires on the events the reference lists: balance transferred to patient, balance paid in full by the payer, patient payment in full or in part, transfer voided, patient balance written off, payment voided, and initial creation. List endpoints return 1,500 rows by default and allow up to 5,000.
The Insurance and Financial section of the reference index also lists Claim Attachment, Claim Note, Collections, Fee Schedule, Insurance Package, Patient Insurance, Patient Insurance Eligibility Information, Payment, Payment Plan, Receipt, Referral Authorization and Statements. I found no remittance or 835 resource in that index. Payer payments appear at the transaction level on the claim.
The pages I read do not state rate limits for the athenaOne APIs, fees for Platform Services or the Marketplace program, or how long validation takes. The documentation flags a Fall 2026 breaking-change release with testing due by October 1, so pin the behaviour you depend on and watch the release notes.