API Change (21.7): athenaTelehealth Visit API

Summary: A new endpoint allows API users to retrieve the link to the athenaTelehealth visit so that it can be displayed or delivered to patient-side attendees via their chosen method (such as a messaging platform or custom patient portal).  

Several existing APIs are updated so that their return payloads include an indicator of whether an appointment is athenaTelehealth. 

Products: athenaCommunicator

Available: 21.7 GA

Highlights: Access to the athenaTelehealth Visit API will benefit clients 

  • who utilize athenaTelehealth but do not utilize ReminderCall. It will allow them to deliver the visit link to patients via their chosen reminder method 
  • who utilize athenaTelehealth but do not use athenahealth's patient portal. It will allow them to take advantage of the Telehealth workflow in their portal of choice 
  • who want to surface the Telehealth workflow in custom applications 


Changes to existing endpoints 

Note: For information about the new endpoint related to this feature, refer to New Endpoint nativeathenatelehealthroom. 


Endpoints Affected: 

Single Appointments - GET /v1/{practiceid}/appointments/{appointmentid} 

Booked Appointments - GET /v1/{practiceid}/appointments/booked 

Changed Appointments - GET /v1/{practiceid}/appointments/changed 


What is changing: 

A new property, nativeathenatelehealth, is now available for these endpoints: Single Appointments, Booked Appointments, and Changed Appointments.  

The property indicates whether an appointment uses native athenatelehealth. It is a Boolean value. 

This includes an optional query parameter named showteleheath and sets it to integer 1. 


Example Request Signature 

GET /v1/1959/appointments/123?showtelehealth=1 


Example Output from Endpoint 



    "appointmentcopay": { 

      "collectedforappointment": 0, 

      "collectedforother": 0, 

      "insurancecopay": 0 


    "appointmentid": "198382", 

    "appointmentstatus": "f", 

    "appointmenttype": "Any 15", 

    "appointmenttypeid": "2", 

    "chargeentrynotrequired": "false", 

    "copay": 0, 

    "date": "04/14/2021", 

    "departmentid": "3", 

    "duration": "15", 

    "patientappointmenttypename": "Any 15", 

    "patientid": "43", 

    "providerid": "2", 

    "starttime": "15:14", 

    "nativeathenatelehealth": true // new property to indicate native athenatelehealth 


Why we’re making this change:  

We’re making this change to allow delivery of athenaTelehealth visit links to patients outside of athenaCommunicator ReminderCall notifications or the Patient Portal. The new and updated APIs will allow MDP partners to retrieve athenaTelehealth visit links and send them to patients via their preferred method (such as MDP partner messaging or a custom portal). Please ensure patients are notified of any changes to how they will receive links for their athenaTelehealth appointments.  


What will current users of this endpoint need to update in their code:  

Users of this endpoint need to update their requests to this endpoint to ask for the showTelehealth parameter if they want to receive that information in the API response.  


What will happen if users of the endpoint do not update their code: 

This is a non-breaking change; however, but they will not be able to receive the new information in the API response if they do not ask for it when querying. 



New Endpoint 


GET /v1/{practiceid}/appointments/{appointmentid}/nativeathenatelehealthroom


Summary Description 

This new endpoint allows an API user to retrieve athenaTelehealth details for a valid athenaTelehealth appointment. It should only be called for valid athenaTelehealth appointments. It can be found by calling the single appointment (appointment) endpoint and checking the nativeathenatelehealth property. 

For MDP documentation, go to: https://docs.athenahealth.com/api/api-ref/appointment



Path Parameters

Item: practiced

Description: The practice/context identifier

Required/Optional: Required

Data Type (object, string, integer): Integer


Item: appointmentid

Description: The appointment identifier 

Required/Optional: Required

Data Type (object, string, integer): Integer


Response Parameters

Response Item: patienturl

Type: String

Description: URL patients use to open the athenaTelehealth web application. It has slashes escaped with backslashes. 

Example: https:\/\/telehealth.px.athena.io\/join\/sometoken.123 


Response Item: jointoken

Type: String

Description: Token associated with a specific telehealth appointment 

Example: sometoken.234 


Response Item: appointmentid 

Type: String

Description: Identifier for appointment 

Example: 8675309



Response: 200

Description: Telehealth details object 


Response: 404

Description: The given appointment is not a telehealth appointment or the appointment is not valid. 

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

On this Page