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

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

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 two 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/partners need worry about unless they are doing something with a new endpoint, in which case you can reach out to our API Design team via creating a salesforce ticket.

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.

Was this information helpful? Yes | No What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

On this Page