Frequently Asked Questions

Please read through our FAQs before rasing a support ticket. We always keep them updated!

Getting Started

  • Where do I find my (API) Key and Secret?

    To access your API Key (Client ID) and Secret (Client Secret), login to your account, and follow the below steps to access your API access details:

    1. Open Applications, and login to your account -
    2. Select your App listed in the dashboard Or create a new application via 'New App'.
    3. Navigate to Credentials in App-section.
    4. Copy the client-id displayed under the credentials tab.
    5. For API secret - either generate a new secret using 'Reset Secret' or provide a previously stored secret from your end.
  • Is there a Sandbox practiceId that I can use to build/test against?

    Yes! Please use Preview practiceId 195900 for all Ambulatory only testing and Preview practiceId 1128700 for all Hospital/Health System testing.

  • For the primary login can we use a group email ID or does the login need to be an individuals email?

    We recommend using the email address for someone who will most likely never leave the company. This is so that if that person does leave, the remaining people on the team do not lose access. Essentially, that person should be responsible for restricting who has access to key and secret information and limit it to only those who are necessary. Please keep in mind that our Best Practice is to use a key management tool and restrict access that way.

    If access is lost, such as in the event that the primary user leaves the company, please submit a ticket using the Request Support buttons located on the right of your screen.

  • What are the Daily API Call Limitations in Preview and Production?

    • API Call Limitations Preview Environments: (path: /preview1) 15 calls/second (QPS); 50,000/day (QPD)
    • API Call Limitations Production Environments: (path: /v1) 100 calls/second (QPS); 500,000/day (QPD)
    • New Token Requests in Preview: 5 per minute rate limit
    • New Token Requests in Production: 50 per minute rate limit

    These limits reset every 24 hours at midnight GMT. Please throttle your calls to stay within your approved limit.

  •  Can third parties send tokens via emails or messages? 

    If you must share your credentials with an authorized party you are required to encrypt those communications. When a token is sent via unencrypted email or message it jeopardizes the security of any associated customer data for that time period.  


    If a third party sends a token via unencrypted message or email, athenahealth will:        

    • Shut off the key for one hour until the exposed bearer token expires. 

    • Audit all API usage of that key for the timeframe in which the token was exposed to ensure the key was not compromised. 

    • Report the incident to athenahealth the Compliance team. 

    • Work with the third party to ensure proper protocol moving forward. 


    Note: athenahealth reserves the right to deactivate your production key if we feel there is a security risk. 

  • Does athenahealth support data conversion/data import?

    athenaNet standard import tools provide additional safety and validation checking to support data conversion/data import. However, our Marketplace APIs were not created to support data conversion projects since we have better tools designed for that purpose. For example, the tools are designed to check for and prevent duplication of records and the API does not check for duplicates in all cases.  


    In circumstances where bad legacy data is received, an entire import batch can be backed out (reverted) at once and our APIs do not provide this critical feature. Posting bad data via API requires an equal number of PUTs/DELETEs to clean up data. This can be extremely difficult and time consuming if it occurs on a large scale. For questions or assistance related to our data import/data conversion capabilities, please contact your Professional Services Project Manager or Customer Success Manager at athenahealth.

  • What data can we move into athenaOne using standard import tools?

    You can import the following athenaCollector data: 

    • Demographics: names, addresses, and other pertinent data 

    • Legacy MRNs and other custom fields 

    • Appointments 

    • Fee and allowable schedules 

    • Referring providers 

           You can also import the following athenaClinicals data:  

    • Problems list 

    • Allergies 

    • Medications 

    • Immunizations 

    • Historical vitals 

    • Unstructured notes (free text notes) 

    • Chart alerts 

  • What are the file formats available for uploading files via API?

    When uploading documents, please note: 

    • Base 64 encoded
    • Content should be multi-part formatted
    • We suggest .pdf for document upload


    Note: If an image upload still fails, especially larger images, try base64 encoding and then try URL encoding. 
    Curl example for posting docs: 


    To learn more, please see File Upload suggestions. 

  • What are the strategies for mitigating server load issues?

    Discuss these with your assigned athenahealth technical lead during the integration project.  
    The performance of the API is more about the amount of processing work needed to compile a response to each call, and less about the absolute number of calls made. 


    For mitigating server loads, there are multiple options. 

    • Parameterize GET calls when possible. 

    • Conduct larger data pulls during off hours (8 p.m. to 6 a.m. EST). 

    • Build a throttling mechanism into your app to regulate the number of calls made. 

    • Leverage subscription endpoints to retrieve changed data. You can call changed data as often as once per minutes. To read more about our subscription functionality, read this page

  • What are character limits and offsets used in API?

    Limits and offsets are used in APIs to help reduce the number of results returned in API calls. To learn more please see here.

  • How can I monitor that athenahealth APIs are up and running, and see their status?

    Partners can use the GET/ping call to monitor if our API is running and see the status. Partners need to enter a practice ID in which their API key has access authorization. To learn more, please refer to this page

  • Are time zones always configured to a specific practice location?

    Any times you see (e.g., in last modified times) are Eastern because we're headquartered outside of Boston, the Hub of the Universe! You can check time zone and daylight savings information for practices using the /departments call. Only the appointment times are local to a practice.

  • Do you support chunked transfer encoding?

    We do not support transfer encoding: chunked for x-www-form-urlencoded POST/PUT calls. (The reasons are complex and confusing, we assure you!)  Our experience is that it works when using multipart/form data, but not with x-www-form-urlencoded calls. 

  • Why do we have missing keys/output parameters in the response data of APIs?

    When new functionality is added to an API, we may add additional fields into JSON hash elements. We make every attempt to not remove documented keys of the response without incrementing versions. A missing key/output parameter in a response is normal if there is no data available for that key.  

  • Why am I unable to log into my account?

    Please keep in mind that users may experience login issues if they’re trying to log in from outside of the United States. If logging in from outside the US, please use a VPN.

  • How do I reset my Developer Portal password?

    When on the login screen for your Developer Portal account, click on “Forgot Password” > Enter your email address > Email me. This will send you a link to get started on your password reset process. 

  • Does athenahealth support SMART on FHIR?

    Yes, athenahealth supports SMART on FHIR for both patient standalone and provider EHR app launch sequences. By definition, SMART on FHIR uses both 3-legged OAuth and FHIR APIs. See our Authorize Endpoint and FHIR API documentation for technical details, then refer to our Onboarding Overview to get started building your app.

Access and Security

  • What type of security does my application require?

    All solutions  

    • Must be on TLS 1.2 or better 

    • Must use credential storage

    Best Practice 

    • Do not hardcode the key and secret into your codebase. Never store credentials directly within the application code. While it can be convenient to test application code with hardcoded credentials during development, this significantly increases risk and should be avoided. 

    • For production deployment, please maintain the key and secret in a centralized place (in this case a key server). The key server is responsible for calling the OAuth endpoint to retrieve and cache the access token (until expiration). It should then make that token available for any users in your environment who need to make an API call. 

    For more information, please see our Best Practices.

  • How do I gain access to an athenaOne customer's Production or Preview environment?

    Access to customer environments varies by app category. Please refer to our Onboarding Overview for those details applicable to your solution.

  • What is the difference between Preview and Production?

    In athenaOne, there are multiple tablespaces, which are groups of data files specific to a client’s practice. athenahealth has two distinct tablespace environments: the preview tablespace aka "sandbox” and the production tablespace. In the preview tablespace, users can build, test and troubleshoot their API solutions using non-sensitive dummy data. The production tablespaces store the client’s live and sensitive health data of patients. Production data is only granted upon a user’s solution being validated.

API Debugging

  • I am facing an error in API responses, what do I do?

    If you’re receiving an error message, please check the Error Conditions list to learn more about the specific error and read the documentation associated with the endpoint. If you require assistance troubleshooting the error in Production, please submit a support case following the guidance in the Request Support tile on the right side of the page or at the bottom of the Sandbox.

  • I am getting Developer Over Rate - Forbidden error. What do I do?

    This is caused by going over your allowed Queries Per Second (QPS) and/or Queries Per Day (QPD) for API calls. If you are experiencing this error frequently please submit a support case.

    Please note that we do not increase call limits for Preview environments; support cases related to QPS/QPD can be submitted for Production only. Our default limits for API calls to Production are 100 queries-per-second and 500,000 queries-per-day. These limits reset every 24 hours at midnight GMT. Please throttle your calls to stay within your approved limit.

  • I keep receiving this error when trying to test my migration: “{"error":"ContextAccessError","detailedmessage":"You do not have access to this context."}

    If you receive the above error, that means you do not currently have access to the context you are attempting to call. If you are in the process of migrating your credentials, please review Step 5 in the migration guidance to find the proper context to hit or next steps to take.


  • How do I report a bug or get production support?

    Please review the Request Support tile located on the right side of this page or at the bottom of the Sandbox.

  • How do I request for an enhancement to be added to my solution?

    If you are an athenahealth Partner you can request an enhancement to an API or request access to an API after your solution has been validated. To do so, please log into your Partner Community account > Support > Manage solutions > Create request. 


    athenahealth Customers should reach out to their Customer Success Manager (CSM) if they would like to make edits to their solution with existing APIs. For ideas regarding net new APIs, please submit this to us as Product Feedback, so that other customers may vote on the ideas. To do this, please log into your Success Community account (athenaOne > Support > Help Resources and Community) > Feedback > Ideas.


    Third-party vendors should reach out to the athenahealth Customer so the Customer can submit the enhancement request. 

  • Where can I go to see any changes to APIs?

    Please review our Change Log to see when and what changes have occurred to APIs.

  • How do I gain access to personal health records?

    athenahealth supports free patient access to health records in athenaOne using Certified APIs and 3-legged OAuth/SMART on FHIR. Apps built to this framework, otherwise known as "personal health record" (or "PHR") apps, allow patients to log in and consent to health record retrieval using their patient portal credentials. See our Onboarding Overview for information on how to create your own PHR app.

  • How can I view the details of an athenaOne feature?

    athenaOne functionality information is stored directly in athenaOne. To access these details, please log into your instance of athenaOne that you have access to (whether that be Preview or Production) > Support > O-help. Search for a word or phrase in O-help, athenahealth’s online help system. O-help content is updated with every athenaOne release. You can search for a quick answer to a question or find Quick Reference and User Guides for more details.  
    Additionally, customers of athenahealth have access to the Success Community where users can review trainings, release notes, and more.

  • Why am I unable to create/edit my apps or reset my secret?

    Unfortunately, you are most likely feeling the effects of an API App Administration outage. These generally are short outages and fall in line with Patient Portal outages. We apologize for any inconvenience this may be causing. 

    If you are a Marketplace Partner, please check your Partner Community account for any notifications from our Marketplace team. Otherwise, you may follow the appropriate support pathway to submit a ticket for assistance as listed in the Request Support tile on the right side of this page or at the bottom of the Sandbox


Frequently Visited Documents

List of frequently accessed documents, articles, and guides.


Request Support

If you can't find a resource, or you need additional support for an error in a Production environment, please open a support case using the buttons below. If you’re an athenahealth Partner, please reach out via the Partner Community by clicking athenahealth Partner Support. If you’re an athenahealth Client – or working on behalf of an athenahealth Client – the athenahealth Client will need to go through the Client Community by clicking athenahealth Client Support.

athenahealth Partner Support athenahealth Client Support