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.

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

    • API Call Limitations Preview Environments: (path: /preview1) 5 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 athenaNet 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. 

Access and Security

  • How do I gain API access to production environment?

    For accessing athena's production environment you need to be either a Marketplace partner or an existing athenahealth client.

    • Marketplace partner - Request you to submit your application in the following form One of our team member will engage with you for next steps.
    • athenahealth clients - If you are developing your own API integration, please contact your Customer Success Manager and have them submit an Integration Request in Salesforce. You’ll be paired with a technical lead to help guide you along and validate your solution.
  • What type of security does my application require?

    A:  All solutions  

    • Must be on TLS 1.2 or better 

    • Must use credential storage 

    • Must pass the Focal Point assessment 


    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:

  • What is the difference between Preview and Production?

    In athenaNet, 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/ “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 answer to How do I report a bug or get production support? in this FAQ. 

  • 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?

    If you are a Marketplace partner and you receive an error message in Production, report these to us by logging into your Partner Community account > Support > Request Support > fill out the “Create Support Case” page. This routes a support case to athenahealth.  


    Customers should create a case via the Success Community > Support or log into athenaNet > Support > Create Case or Call. In most situations, the type of help you need would be related to “Interfaces & Integration”.   


    Third-party vendors should communicate with customers who can submit a support ticket on your behalf. 

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

    If you are a Marketplace 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 > Request an Enhancement. This routes a ticket to the Marketplace Operations team to review and triage appropriately.  


    Customers should reach out to their Customer Success Manager 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 as well. To do this, please log into your Success Community account (athenaNet > Support > Help Resources and Community) > Feedback > Ideas.  


    Third-party vendors should reach out to the customer so that they 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 (patient app launch, SMART on FHIR (3 Legged OAuth), 3 Legged FHIR API, patient authentication, etc)?

    athenahealth does not yet provide an EMR launch flow, but we have plans to support this feature in the future. To be notified when this functionality becomes available for testing, contact our Marketplace team at and include details of your application indicating your request to use the EMR launch flow for FHIR.

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

    athenaNet functionality information is stored directly in athenaNet. To access these details, please log into your instance of athenaNet that you have access to (whether that be Preview or Production) > Support > athenaNet O-help. Search for a word or phrase in O-help, athenahealth’s online help system. O-help content is updated with every athenaNet 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. 



Frequently Visited Documents

List of frequently accessed documents, articles and guides


Request Support

If you have any questions and are in need of support, please use the following links below. If you’re a Marketplace Partner, please reach out via the Partner Community by clicking Marketplace Support. If you’re a Client – or working on behalf of a Client – the Client will need to go through the Client Community by clicking Platform Services Support.

Marketplace Support Platform Services Support