Changed Data Subscriptions

For certain data, such as booked appointments ("appointments" replacing "feedtype" below), we allow you to subscribe to a feed that will output changes, similar to an HL7 interface. Below you will find subscription feeds including hospital. 

Process overview

 1. Subscribe to a data feed with the POST/{feedtype}/subscription API. If you only want to subscribe to one event, there are two calls to utilize.

  • GET/{feedtype}/changed/subscription/events returns a list of all possible event names that may be subscribed to via the POST API. example:
  • When inputting an event name into the POST call, 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.
  • Please note that any changes to subscriptions (POST/DELETE) will take up to 5 minutes in production (and sometimes up to 10-15 minutes in preview).

2. Retrieve changed data using the GET/{feedtype}/changed API. Example:

3. Partial Subscriptions will be displayed via the GET/{feedtype}/subscription call with a status of “Partial”. Example:

Note: When executing a POST / DELETE API without including an event name, the API wil modify all possible event names. 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 execute using just one event name, only events matching will be removed from the subscription. Subscriptions are specific to each API key and changes or calls are not affected by other API keys.

Overview of Individual Change Events

Appointments Changed

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

Encounters

For practices using athenaClinicals, appointments/changed can also be used to retrieve Encounters. Encounters are created in athenaNet when an appointment is checked in, thus using the Check In event and the "encounterid" output parameter is equivalent to the commonly requested "GET /encounters/changed" "Event=Create Encounter" endpoint.

Notes: 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.

Once you make a POST to /appointments/changed/subscription for a given practice, there is no need to call it again (unless you DELETE it, of course).   Please note that the DELETE action removes all subscriptions for a particular feed type.

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.

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.

Retrieving Changed Appointments Data

To retrieve data from a changed appointments feed you will need to run the GET /appointments/changed API for one or more practices. This call is the same as /appointments/booked, but returns the set of appointments that have changed. 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.)

Due to the volume of messages that can accumulate fairly quickly, you must call the .../changed call routinely. athenaNet will automatically remove messages from the queue that are not retrieved. This is currently set up to delete messages older than 24 hours. However, 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. (If we lower this, we will likely take into account that many partners have maintenance windows overnight. We'll be sure to announce this in the change log as well.) 

Patients Changed

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.

    Problems Health History Changed

    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.

    Medication Health History Changed

    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

    Allergies Health History Changed

    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 

    Family Health History Changed 

    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 

    Vaccine Health History Changed 

    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 

    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.

    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. 

    Prescriptions Changed

    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:

    • Delete a Prescription
    • Update a Prescription

    Note: Newly-added prescriptions will not be included in the Prescriptions Changed results. All other functionality mirrors the Appointments example above.

      Patient Case Changed 

      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

      Imaging Results Changed

      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 susbscription to the following imaging results- related events: 

      • Add Imaging Result 
      • Add Result 
      • Delete Result 

      Lab Results Changed

      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 

      Hospital Visits Changed

      To activate a subscription to a hospital or health system's visit creatd 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 

        Hospital Stays Changed

        To activate a subscription to a hospital or health system's stays creatd 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 

        Hospital Or-case Changed

        To activate a subscription to a hospital or health system's orcase 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 orcase- related events: 

        • Created Preference Card
        • Update  Preference Card 
        • Consumptions Submission 

        Hospital SurgeryCase Changed

        To activate a subscription to a hospital or health system's surgery case creatd 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 

        Hospital Charge Codes Changed

        To activate a subscription to a hospital or health system's charge code creatd 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 

        CCM Enrollment Status Changed

        To activate a subscription to a practice's CCM enrollement 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 enrollement statusr-related events:  

        • Update CCM Status 

        Claims Changed

        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.

        Providers Changed 

        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 

        Provider Numbers Changed 

        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 providernumber-related events:  

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

        Referring Providers Changed 

        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 

        Referring Provider Numbers Changed

        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

        Generally Available

        Ambulatory

         

        Inpatient

         

        Behind Rollout Toggles

        All events are listed below are 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 What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

        On this Page