API Change (22.1): Batch Update to API Subscriptions to Leverage Department Filtering

(Updated as of 3/1/22)


Previously (in releases prior to 21.7), you were not allowed to limit API subscriptions to specific departments when retrieving changed information. This resulted in the creation of a significant number of unnecessary transactions that caused a strain on the API infrastructure.

In 21.7 and all subsequent releases, department filtering can now be implemented on the Subscription POST call.

Subscription Cleanup

To cleanup subscriptions, athenahealth will be running a batch update for all client and partner subscriptions (POST calls) to add the appropriate Department filter to your subscriptions. 

Note: Department IDs to set in the Department Filter for each Changed Subscription have been determined by analyzing what messages have been retrieved (GET calls) by the client/partner in the prior 90 days (e.g.,1st Oct’21 – 31st Dec’21)

Products: athenaClinicals, athenaCollector 

Related Information: See Subscribe Data Feed Types to Individual Departments

Available: 22.1 GA


  • Subscribing data feeds to a list of individual departments within a practice reduces the number of unnecessary and costly subscriptions that are never actually consumed by the practice/partner, improving overall performance.


Endpoints affected  

Below is the list of endpoints affected. 

Format: POST/ <feedtype>/changed/subscription 

  1. POST/appointments/changed/subscription  
  2. POST/imagingresults/changed/subscription  
  3. POST/labresults/changed/subscription  
  4. POST/orders/changed/subscription
  5. POST/visits/changed/subscription  
  6. POST/claims/changed/subscription  
  7. POST/patients/changed/subscription 

What is changing?  

The new parameter to the POST request, introduced in the Summer 2021 release, allows partners to subscribe to specific departments within a practice.

As a FINAL STEP to this feature update, athenahealth will run a one-time batch job to set the appropriate Department Filter on each instance of the above subscription endpoints for all clients and partners. We have reviewed your specific call patterns to identify the appropriate values to set based on the Department IDs for which you have RETRIEVED /changed data in the past 90 days.

This update is scheduled to run on January 31st 2022.

Why we’re making this change  

Subscriptions to data feed were previously only available at the practice (context) level, resulting in many unused subscriptions, where data was not being processed. To minimize performance issues, we have enhanced the functionality to allow you to subscribe at a department ID-level.

Is this a breaking change?  


What do I need to update in my code?  

Initially, athenahealth will automatically update existing subscriptions. However, for all future updates to these subscriptions, you must update your filters in the POST subscription call to MATCH the same filters that you use when retrieving the messages. The important rule to follow is: If you are filtering to only retrieve messages for specific departments, you should also ensure you only creating subscriptions for those same departments.

What will happen if you do not update your code?  

If you do not include department filters in your POST subscription, athena will continue to generate and storing millions of messages that people don't need and don't retrieve. This adds significant unnecessary load on the API infrastructure which risks performance and stability for the system as a whole. Please ensure you use department-filters when using the POST subscription call whenever possible.

Note: Once athena has applied filters as part of the release, you will need to monitor your filters as new departments are added to athena and update your subscriptions.

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

On this Page