Best Practices and Troubleshooting

Character Limits and Offsets

Limits and Offsets are used in APIs to help reduce the amount of results returned in API calls.  


Limits are used to return a subset of information.  If we have a collection that returns a list of items, and the amount of those items is greater than the LIMIT input, we stop returning them after that amount.  For example, if the items to be returned are IDs => [ 1,2,3,4,5,6,7,8,9,10 ] and we use a limit of 3, the output of the API would be IDs => [1,2,3].

Most fields in the patient API are limited to a maximum of 20 characters. There are a few exceptions to the 20-character limit:

Patient Field Limits

Field Name Character Limit
Lastname field   30
Address1/2   100
City, Guarantor City   30
State, Guarantor State   10
All Zips  10
SSN   13
Employer name   100
Contact name   50
Email 50
Employer city   40
Employer address   80
Name suffix   10


Offsets are used to return information from API calls starting at a specified value.  If more results are desired, you can use the OFFSET to get the next "page" of results. Using the same example above returning IDs => [ 1,2,3,4,5,6,7,8,9,10 ] we could use an offset of 3 and get IDs => [4,5,6,7,8,9,10,11,12,13].

Using the two in combination such as using a limit of 3 and an offset of 3 would return IDs => [4,5,6].

Note: Certain APIs have built in default limits which necessitates the ability to handle them gracefully. 


Server Load Mitigation and Data Backfills

Data Backfills

As our community of users continues to grow, we are proactively working to ensure consistent API uptime with limited outage risk. As a result, we will not accept integrations that necessitate the import of bulk data from one system to another. We acknowledge that the onboarding period for a client might require a temporary period where basic practice data is collected to configure an integration; and this is something we discuss with users during the development stage of every project. 

Call Volume & Filtering

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. This is something you will discuss with your assigned athena technical lead during the integration project, but keep these guidelines in mind when putting together your initial documentation.

The following calls are particularly intensive on our system: 

  • GET /patients 
  • GET /appointments/booked 
  • GET /appointments/booked/multipledepartment
  • GET /claims 

We recommend a few different strategies for mitigating server load issues:

  1. Parameterizing GET calls when possible.

  2. Conducting larger data pulls during "off hours" (8pm - 6am EST).

  3. Building a throttling mechanism into your app to regulate the number of calls made. 

  4. Leveraging subscription endpoints to retrieve changed data. You can call changed data as often as once per minute. To read more about our subscription functionality, visit this page.

If your solution requires GET /appointments/booked, we will ask you to limit your call scope to a defined range of days before and after the appointment date. For claims, we recommend a range of 3-6 months of past data based on the parameters used to filter the call, and how often the call needs to be made. If your solution requires GET /patients, we will ask you to parameterize those calls or recommend that you use GET /patients/enhanced best match as an alternative. 

  • Note that this range will be more limited if you are not caching data. 
  • For enterprise clients, please reduce the scope of your data pull as much as possible. 


File Upload

When uploading documents we suggest you to follow the following best practices:

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

If image uploads still fail (especially for larger images) try base64 encoding, then URL encoding.

Handling Beta APIs

Some of the Beta APIs are rolled out for limited practices, and are behind athenaOne rollout features. In other words, you may see some of these Beta APIs working for some practices in your App, but resulting in error for a different set of practices. Expanding and rolling out the feature/Beta APIs to additional contexts are controlled by athena and is an internal process. Our standard practice is to apply these rollouts globally once they have been confirmed to operate correctly without issues. Rollouts are no longer anything that users should need worry about unless they are doing something with a new endpoint, in which case Marketplace Partners should contact their Partner Success Manager, and all other API users should work with a Customer Success Manager to submit an Integration Request.

If you need help understanding and debugging some API issues you are seeing, please feel free to review our additional reference documentation and workflow documentation. We are always happy to review, and answer questions related to the functionality of an API. However, if you believe you have found an API bug in Production, please feel free to submit a support case through Success Community with specific examples and input parameters so a larger staffed team can review.

Additional Notes

Throughout the build and eventual validation of a solution, the following issues should be proactively addressed: 

1. User Authentication for Surfacing PHI: 

  • Concern: Surfacing PHI to incorrect patients, etc 

  • Workflow/ API Solutions: 

  • Registration and log-in with 2-factor authentication (text/email). This should be in accordance with the regulations established by the relevant state, etc. 

  • For more information see here.  

2. Patient Matching Safety/Compliance: 

  • Concern: Duplicative patient entry or updates to incorrect patient charts  

  • Workflow/API Solution: To match patients, be sure to pass at least 4 input parameters 

  • Required Parameters: First name, Last name, DOB, fourth parameter: email, phone number, Zip Code, SSN, etc

Relevant API Calls: 

  • GET/POST/PUT /patients 
  • GET /patients/search 
  • GET /patients/enhancedbestmatch 

      For more information see here.

3. Security Compliance: 

  • Concern: clientid/secret storage 

  • Solution: Maintain your athenahealth clientid and secret in a centralized place (a key server) for a higher level of security and restrict the amount of people who can access the key/server.   

  • Do not check the key/secret within any codebases 

  • Never send bearer tokens, keys, and secrets over unencrypted email.  

4. API Call Limitations: 

  • Concern: Placing too many API Calls outside of the limitations, compromises all of athenaNet 

  • Solution: Adhere to pre-established limitations: 

  • Preview Environments: (path: /preview1) 5 calls/second; 50000/day 

  • Production Environments (path: /v1) 50/sec, 500000Utilize subscription endpoints. See here for more information. 

  • Limit large data pulls. See here for more information. 

  • Relevant API Calls: 

  • All calls, especially: GET /patients GET /booked/open/appointments

5. Updating Patient Chart Information 

  • Concern:Only athenaNet practice users can update the chart. Patients cannot update their chart information. 

  • Solution: Utilize and post Health History Forms or CCDAs as those initiate reconciliation task 

Relevant API Calls: 

Discrete data points within a patient’s chart like:

  • POST /chart/{patientid}/vitals /preview1/:practiceid/chart/:patientid/vitals 
  • POST /chart/{patientid}/problems 
  • /preview1/:practiceid/chart/:patientid/problems 
  • POST /chart/encounter/{encounterid}/diagnoses 
  • /preview1/:practiceid/chart/encounter/:encounterid/diagnoses 

Lack of compliance and proactive integration of the aforementioned solutions, along with any other issues, will result in a failed Solution Validation, along with the reassessment of the solution.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

On this Page