Changed Data Subscriptions

Overview

athenahealth API solutions allow you to subscribe to polling-based changed data feeds, similar to an HL7 interface, for certain data in athena. We offer different types of changed data feeds, including hospital. You can choose to subscribe to all events or individual events within a changed data feed (e.g., appointment create, appointment update). 

 

The workflow for using our subscription feeds is below: 

Subscribe to a changed data feed: 

  1. If you want to subscribe to all events in a data feed, use POST   {feedtype}/changed/subscription API to subscribe to all events in a data feed.

Example: POST   /v1/{practiceid}/documents/patientcase/changed/subscription

  1. If you only want to subscribe to one event, there are two calls to utilize:
    • Use GET   /{feedtype}/changed/subscription/events to get a list of all possible event names that may be subscribed.

Example: GET   /v1/{practiceid}/documents/patientcase/changed/subscription/events

    • Use POST   /{feedtype}/changed/subscription and pass an event name in input parameter. Only one event is allowed for input into the POST. The POST API call will need to be called for each single event if multiple, but not all, are desired.

  1. Starting in 21.7 release, we have added a new functionality to allow data feed subscription for specific departments within a practice (more information here). The important rule to follow is: If you are filtering to only retrieve messages for specific departments, you should also consider only creating subscriptions for those same departments. This helps alleviate unnecessary load on our API infrastructure and mitigate risks on performance and stability for our system as a whole.
 

Get a list of subscribed events: 

Use GET   /feedtype}/changed/subscription call to get a list of events you subscribed to. Partial Subscriptions will be displayed via the GET   /{feedtype}/subscription call with a status of “Partial”.

 

Retrieve changed data: 

Retrieve changed data using the GET   /feedtype}/changed API.

 

Unsubscribe to all or select events in a changed data feed: 

Use DELETE   /{feedtype}/changed API to delete an entire subscription or specific events that are no longer needed

 

Important Notes & Best Practices 

  • The volume of queued messages generated from these subscriptions can accumulate very quickly. athena automatically deletes messages from the queue that are older than 24 hours and are not retrieved. We reserve the right to lower this to as low as 1 hour, so we ask that you retrieve messages at least once an hour to keep your message queue small.

  • Unused subscriptions result in a significant number of unnecessary changed event messages that put pressure on our API infrastructure. To conserve our infrastructure and improve overall performance, starting in Oct 2022, we will automatically remove any changed subscriptions older than 7 days and with no /changed API call made to retrieve the data in the last 7 days. It is your responsibility to re-subscribe to these changed feeds if there is future need for the changed data. Once re-subscribed, events will begin queuing into your feed from the time of resubscribing.

  • Any changes to subscriptions (POST/DELETE) will take approximately 10 minutes or more in production (and sometimes up to 15-20 minutes in preview).

  • When executing a POST / DELETE API without including an event name, the API will modify your subscription for all possible events. If the POST call is executed using just one event name, only events matching the subscription will be returned. Similarly, if the DELETE call is executed using just one event name, only events matching will be removed from the subscription.

  • POST/ call to set up a new changed subscription is intended to be a one-time call. You do not need to re-subscribe unless the subscription you set up has been deleted.

  • By default, retrieving the changed data (e.g., appointments) will remove them from the queue of appointments that are returned. There is no mechanism (or need) to mark the data as received. (For the purpose of debugging, there is a flag you can use to not remove messages from the queue.)

  • Subscriptions are specific to each API key and changes or calls are not affected by other API keys.
     

Individual Changed Events 

Feed Type 

Event Details 

AMBULATORY 

Appointments 

To activate a subscription to a practice's appointments changed feed, use the POST to appointments/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following appointment-related events: 

  • Create Appointment 
  • Cancel Appointment 
  • Update Appointment 
  • Check In 
  • Check Out   
  • Update Call Reminder (optional) 
  • Freeze Appointment 
  • Unfreeze Appointment 

To retrieve data from a changed appointments feed you will need to run the GET /appointments/changed API for one or more practices. 

Notes:  

  1. To retrieve Encounters that were created in athenaNet when an appointment is checked in, you can use appointments/changed and subscribe to Check In event. The output parameter will return the “encounterid” of all applicable encounters. 
  2. In order to subscribe to the optional Update Call Reminder event, you must set the includeremindercall field to True in the POST /appointments/changed/subscription.  When set to True, a complete subscription will include all of the appointment subscription events plus UpdateCallReminder.  If the includeremindercall field isn’t set to True, a complete subscription will include all the events except UpdateCallReminder. 
  3. In the case when you want to utilize this subscription at a large athena practice (e.g. 400 departments), consider the following recommendations to improve performance: 
    • Use the default limit of 1000 
    • Use department filtering. For example, instead of calling the /changed endpoint for the entire practice (400 departments), use 20 separate calls with 20 departments each. 
    • Increase call frequency to the /changed endpoint. An increased frequency (e.g. once every 1 min) means less likelihood of new unseen events and reduced risk of exceeding the 1000 limit. 
    • Call frequency should NEVER exceed GET/{feedtype}/changed per minute 
    • Wait for a response before calling /changed on the same department again. This endpoint is not designed to support two unanswered /changed calls for the same department at any moment. 

Click here for more details on appointments changed endpoints 

Patients 

 

To activate a subscription to a practice's patients changed feed, use the POST to /patients/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following patient-related events: 

  • Add Patient 
  • Delete Patient 
  • Update Patient 
  • Merge Patient 

All other functionality mirrors the Appointments example above. 

Click here for more details on patients changed endpoints 

Problems Health History 

 

To activate a subscription to a practice's problem created feed, use the POST to /chart/healthhistory/problems/changed/subscription API.  Once activated for a practice, this call sets up a subscription to the following problem changed-related events:   

  • ProblemAdd 
  • ProblemUpdate 

Note: Problems with an event type of 'Start' are active health history problems for a patient. 

Click here for more details on problem health history changed endpoints 

Medication Health History 

 

To activate a subscription to a practice's medication created feed, use the POST to /chart/healthhistory/medication/changed/subscription API.  Once activated for a practice, this call sets up a subscription to the following medication changed-related events:   

  • MedicationHxAdd 
  • MedicationHxUpdate 
  • MedicationHxDelete 

Click here for more details on medication health history changed endpoints 

Allergies Health History 

 

To activate a subscription to a practice's allergies changed feed, use the POST to /chart/healthhistory/allergies/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following allergy-related events: 

  • Allergy Update 
  • Allergy Add 

Click here for more details on allergies health history changed endpoints 

Family Health History 

 

To activate a subscription to a practice's family history changed feed, use the POST to /chart/healthhistory/familyhistory/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following family history- related events: 

  • Family Hx Add  
  • Family Hx Update 

Click here for more details on family health history changed endpoints 

Vaccine Health History 

 

To activate a subscription to a practice's vaccine changed feed use the POST to /chart/healthhistory/vaccine/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following vaccine- related events  

  • Hx Vaccine Add  
  • Hx Vaccine Update  
  • Hx Vaccine Delete 

Click here for more details on vaccine health history changed endpoints 

Orders Created 

 

To activate a subscription to a practice's orders created feed, use the POST to /orders/changed/subscription API.  Once activated for a practice, this call sets up a subscription to the following orders changed-related events:   

  • Administer Vaccine 
  • Deny Order 
  • Create Order 

Note: For orders created in a new order group, the encountertype will be listed as "Orders Only".  This signifies that the order was created outside of an encounter visit. 

Click here for more details on orders changed endpoints 

Orders Signed Off 

 

To activate a subscription to a practice's orders signed off feed, use the POST to /orders/signedoff/subscription API. Once activated for a practice, this call sets up a subscription to the following order signoff-related events: 

  • An Order for Lab, Imaging, DME, Surgery/Px, Referral, Patient Info or Other is signed off 
  • A Documentation-only order for Medication or Vaccine is signed off 

Note: An order is considered signed-off when the Sign orders checkbox is checked and the order is saved in athenaClinicals. A Documentation-only order is considered signed-off when the Documentation only and Sign orders checkboxes are checked and the order is saved in athenaClinicals. All other functionality mirrors the Appointments example above. 

Click here for more details on orders changed endpoints 

Prescriptions 

 

To activate a subscription to a practice's prescriptions changed feed, use the POST to /prescriptions/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following prescription-related events: 

  • Add a Prescription 
  • Delete a Prescription 
  • Update a Prescription 
  • Add Prescription Refill 
  • Reopen a Prescription 
  • Preapprove a Prescription 
  • Update the Refill of a Prescription 

Click here for more details on prescriptions changed endpoints 

Patient Case 

 

To activate a subscription to a practice's patient case created feed, use the POST to / documents/patientcase/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following patient case-related events:  

  • Add Patient Case  
  • Update Patient Case 

Click here for more details on patient case changed endpoints 

Imaging Results 

 

To activate a subscription to a practice's imaging results created feed, use the POST to /imagingresults/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following imaging results-related events:  

  • Add Imaging Result  
  • Add Result  
  • Delete Result 

Click here for more details on imaging results changed endpoints 

Lab Results 

 

To activate a subscription to a practice's lab results created feed, use the POST to /labresults/changed/subscription API. Once activated for the practice, this call sets up a subscription to the following lab results-related events:  

  • Add Lab Result  
  • UpdateLab Results 

Click here for more details on lab results changed endpoints 

CCM Enrollment Status 

 

To activate a subscription to a practice's CCM enrollment status created feed, use the POST to /ccmenrollementstatus/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following CCM enrollment status-related events:   

  • Update CCM Status 

Click here for more details on CCM enrollment status changed endpoints 

Claims 

 

To activate a subscription to a practice's claim status created feed, use the POST to /claims/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following claim-related events:  

  • Update Claim 
  • Create Claim (optional)  

Note: In order to subscribe to the optional Create Claim event, you must set showadditionalevents to True in the POST /claims/changed/subscription. When set to True, a complete subscription will include all  Claim changed events including Create claim. If the showadditionalevents field isn’t set to True, a complete subscription will include all the events except CreateClaim. 

Click here for more details on claims changed endpoints 

Providers 

 

To activate a subscription to a practice's providers created feed, use the POST to /providers/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following provider-related events:   

  • Add a Provider  
  • Update a Provider  
  • Delete a Provider  
  • Undelete a Provider 

Click here for more details on providers changed endpoints 

Provider Numbers 

 

To activate a subscription to a practice's provider numbers created feed, use the POST to /providernumbers/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following provider number-related events:   

  • Add a ProviderNumber  
  • Update a ProviderNumber  
  • Delete a ProviderNumber 

Click here for more details on providers number changed endpoints 

Referring Providers 

 

To activate a subscription to a practice's referring providers created feed, use the POST to /referringproviders/changed/subscription API. Once activated for a practice, this call sets up a subscription to the following referring provider-related events:  

  • Add a Referring Provider  
  • Update a Referring Provider  
  • Delete a Referring Provider  
  • Undelete a Referring Provider 

Click here for more details on referring providers changed endpoints 

Referring Provider Numbers 

 

To activate a subscription to a practice's referring provider numbers created feed, use the POST to /referringprovidernumbers/changed/subscription API.  Once activated for a practice, this call sets up a subscription to the following referring provider numbers-related events:  

  • Add a Referring Provider Number  
  • Update a Referring Provider Number 

Click here for more details on referring provider numbers changed endpoints 

INPATIENT 

Hospital Visits 

 

To activate a subscription to a hospital or health system's visit created feed, use the POST to /stays/changed/subscription API. Once activated for the hospital or health system, this call sets up a subscription to the following visit-related events:  

  • Admit ER Patient  
  • Admit Patient  
  • Encounter Update  
  • Undelete Outpatient Visit  
  • Undelete Inpatinet Visit  
  • Delete Visit  
  • Discharge Visit 

Click here for more details on hospital visits changed endpoints 

Hospital Stays 

 

To activate a subscription to a hospital or health system's stays created feed, use the POST to /stays/changed/subscription API. Once activated for the hospital or health system, this call sets up a subscription to the following stay-related events:  

  • Create Stay  
  • Admit Stay  
  • Cancel Stay  
  • Discharge Stay  
  • Transfer Stay  
  • Care TeamStay  
  • Close Stay  
  • Update location  

Note:  

  1. Only the attending, admitting, and discharging providers will be included in the CareTeam Stay. This event will be triggered when one of these care team members is added, updated, or removed from the care team. 
  2. AdmitStay will update when an admission order is signed 
  3. Discharge stay will update when any section of the discharge plan is saved 

Click here for more details on hospital stays changed endpoints 

Hospital Operating Room (OR) Cases 

 

To activate a subscription to a hospital or health system's OR case created feed, use the POST to /orcase/changed/subscription API. Once activated for the hospital or health system, this call sets up a subscription to the following OR case-related events:  

  • Created Preference Card 
  • Update  Preference Card  
  • Consumptions Submission 

Click here for more details on hospital OR case changed endpoints 

Hospital Surgery Case 

 

To activate a subscription to a hospital or health system's surgery case created feed, use the POST to /surgerycases/changed/subscription API. Once activated for the hospital or health system, this call sets up a subscription to the following surgery case-related events:  

  • Create Surgery Case 
  • Update Surgery Case 
  • Delete Surgery Case 

Click here for more details on hospital surgery case changed endpoints 

Hospital Charge Codes 

 

To activate a subscription to a hospital or health system's charge code created feed, use the POST to /chargecodes/changed/subscription API. Once activated for the hospital or health system, this call sets up a subscription to the following charge code- related events:  

  • Deny Charge Code  
  • Map Charge Request 

Click here for more details on hospital charge codes changed endpoints 

Beta Changed Data APIs

All changed subscriptions APIs listed below are in Beta status and behind rollout toggles. If individual events are listed, they are the only ones behind rollout toggles for that subscription. See Permissioned Rollout of APIs for access. 

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

On this Page