Appointment

The Appointment API feature allows the user to book a patient appointment with the provider, reschedule an existing appointment, cancel an existing appointment. This feature also allows the user to delete an existing appointment time slot of the Provider so that no patient can book an appointment in that time slot.

The Appointment Changed Subscription feature will allow the user to retrieve changes to appointments (generally scheduled, cancelled, check-in) or changes to the provider appointment slots. The user will need to subscribe. For more information about subscriptions, please refer Changed Data Subscriptions.

The athena Telehealth Room feature retrieves details for a valid native athenaTelehealth appointment. Be aware that the invite link is to an unauthenticated web app. Clients should first check if their appointment is a native athenaTelehealth appointment by using our single appointment endpoint GET /appointments/{appointmentid}, our appointment changed data subscription GET /appointments/changed, or our booked appointment slots endpoint GET /appointments/booked. The patient url and join token are only valid on the day of the appointment. Please communicate the device check link (https://telehealth.px.athena.io/device-check) in your patient messaging.

 

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

Book appointment

PUT
/v1/{practiceid}/appointments/{appointmentid}
Create a single appointment for specific patient
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
appointmentid integer appointmentid
Content-Type string Content type of the payload

Request Body

Expand all

Output Parameters

Expand all
appointmentcopay string Detailed information about the copay for this appointment. Gives more detail than the COPAY field. Note: this information is not yet available in all practices, we are rolling this out slowly.
appointmentid string Appointment ID of the booked appointment
appointmentstatus string The athenaNet appointment status. There are several possible statuses. x=cancelled. f=future. (It can include appointments where were never checked in, even if the appointment date is in the past. It is up to a practice to cancel appointments as a no show when appropriate to do so.) o=open. 2=checked in. 3=checked out. 4=charge entered (i.e. a past appointment).
appointmenttype string The practice-friendly (not patient friendly) name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
appointmenttypeid string This is the ID for the appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
chargeentrynotrequired string This field will tell if an appointment has been marked as not requiring change entry.
chargeentrynotrequiredreason string This field will give the reason that an appointment has been marked as not requiring charge entry.
claims array As detailed in /claims, if requested.
copay string Expected copay for this appointment. Based on the appointment type, the patient's primary insurance, and any copays collected. To see the amounts used in this calculated value, see the APPOINTMENTCOPAY fields.
date string The appointment date.
departmentid string
duration integer In minutes
encounterid string The encounter id associated with this appointment, useful for certain other calls. Only present for appointments with Clinicals that have been checked in.
encounterprep string If true, encounter prep has been started for the encounter associated with this appointment.
encounterstate string The status of the clinical encounter associated with this appointment (OPEN, CLOSED, DELETED, PEND, etc.). This differs from encounterstatus, which refers to the status of the patient in the encounter.
encounterstatus string The status of this patient in the encounter (READYFORSTAFF, WITHSTAFF, READFORPROVIDER, CHECKEDOUT). Only present for appointments with Clinicals that have been checked in.
frozenyn string If true, this appointment slot is frozen
hl7providerid integer This is the raw provider ID that should be used ONLY if using this appointment in conjunction with an HL7 message and with athenahealth's prior guidance. It is only available in some situations.
insurances array List of active patient insurance packages. Only shown for single or multiple booked appointments if SHOWINSURANCE is set.
patient string As detailed in /patients, if requested.
patientappointmenttypename string The patient-friendly name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
patientid string The athenaNet patient ID for this appointment
patientlocationid string The location of the patient. See /patientlocation for practice list. Only present for appointments with Clinicals that have been checked in.
providerid string
referringproviderid integer The referring provider ID.
renderingproviderid integer The rendering provider ID.
rescheduledappointmentid string When an appointment is rescheduled, this is the ID of the replacement appointment.
startcheckin string The timestamp when the appointment started the check in process. If this is set while an appointment is still in status 'f', it means that the check-in process has begun but is not yet completed.
starttime string As HH:MM (where HH is the 0-23 hour and MM is the minute). This time is local to the department.
stopcheckin string The timestamp when the check-in process was finished for this appointment.
supervisingproviderid integer The supervising provider ID.
urgentyn string Urgent flag for the appointment.
useexpectedprocedurecodes array An array of expected procedure codes attached to this appointment.
Example Code

Get appointment details

GET
/v1/{practiceid}/appointments/{appointmentid}
Retrieves the details of a specific appointment. Note: This endpoint may rely on specific settings to be enabled in athenaNet Production to function properly that are not required in other environments. Please see Permissioned Rollout of APIs for more information if you are experiencing issues.
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
appointmentid integer appointmentid
showcopay boolean By default, the expected co-pay is returned. For performance purposes, you can set this to false and copay will not be populated.
showclaimdetail boolean Include claim information, if available, associated with the appointment.
showinsurance boolean Include patient insurance information.
showexpectedprocedurecodes boolean Show expected procedure codes
showpatientdetail boolean Include patient information for each patient associated with an appointment.
showtelehealth boolean Show indicator for if this is a native athenatelehealth appointment
ignorerestrictions boolean When showing patient detail for appointments, the patient information for patients with record restrictions and blocked patients will not be shown. Setting this flag to true will show that information for those patients.

Output Parameters

Expand all
appointmentcopay string Detailed information about the copay for this appointment. Gives more detail than the COPAY field. Note: this information is not yet available in all practices, we are rolling this out slowly.
appointmentid string Appointment ID of the booked appointment
appointmentstatus string The athenaNet appointment status. There are several possible statuses. x=cancelled. f=future. (It can include appointments where were never checked in, even if the appointment date is in the past. It is up to a practice to cancel appointments as a no show when appropriate to do so.) o=open. 2=checked in. 3=checked out. 4=charge entered (i.e. a past appointment).
appointmenttype string The practice-friendly (not patient friendly) name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
appointmenttypeid string This is the ID for the appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
chargeentrynotrequired string This field will tell if an appointment has been marked as not requiring change entry.
chargeentrynotrequiredreason string This field will give the reason that an appointment has been marked as not requiring charge entry.
claims array As detailed in /claims, if requested.
copay string Expected copay for this appointment. Based on the appointment type, the patient's primary insurance, and any copays collected. To see the amounts used in this calculated value, see the APPOINTMENTCOPAY fields.
date string The appointment date.
departmentid string
duration integer In minutes
encounterid string The encounter id associated with this appointment, useful for certain other calls. Only present for appointments with Clinicals that have been checked in.
encounterprep string If true, encounter prep has been started for the encounter associated with this appointment.
encounterstate string The status of the clinical encounter associated with this appointment (OPEN, CLOSED, DELETED, PEND, etc.). This differs from encounterstatus, which refers to the status of the patient in the encounter.
encounterstatus string The status of this patient in the encounter (READYFORSTAFF, WITHSTAFF, READFORPROVIDER, CHECKEDOUT). Only present for appointments with Clinicals that have been checked in.
frozenyn string If true, this appointment slot is frozen
hl7providerid integer This is the raw provider ID that should be used ONLY if using this appointment in conjunction with an HL7 message and with athenahealth's prior guidance. It is only available in some situations.
insurances array List of active patient insurance packages. Only shown for single or multiple booked appointments if SHOWINSURANCE is set.
nativeathenatelehealth string If true, then this is a native athenatelehealth appointment.
patient string As detailed in /patients, if requested.
patientappointmenttypename string The patient-friendly name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
patientid string The athenaNet patient ID for this appointment
patientlocationid string The location of the patient. See /patientlocation for practice list. Only present for appointments with Clinicals that have been checked in.
providerid string
referringproviderid integer The referring provider ID.
renderingproviderid integer The rendering provider ID.
rescheduledappointmentid string When an appointment is rescheduled, this is the ID of the replacement appointment.
startcheckin string The timestamp when the appointment started the check in process. If this is set while an appointment is still in status 'f', it means that the check-in process has begun but is not yet completed.
starttime string As HH:MM (where HH is the 0-23 hour and MM is the minute). This time is local to the department.
stopcheckin string The timestamp when the check-in process was finished for this appointment.
supervisingproviderid integer The supervising provider ID.
urgentyn string Urgent flag for the appointment.
useexpectedprocedurecodes array An array of expected procedure codes attached to this appointment.
Example Code

Cancel appointment

PUT
/v1/{practiceid}/appointments/{appointmentid}/cancel
Allows the user to cancel a scheduled appointment
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
appointmentid integer appointmentid
Content-Type string Content type of the payload

Output Parameters

Expand all
status string The status of this appointment after the operation (generally "x").
Example Code

Reschedule appointment

PUT
/v1/{practiceid}/appointments/{appointmentid}/reschedule
Reschedules an existing appointment to a new timeslot provided by the patient
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
appointmentid integer appointmentid
Content-Type string Content type of the payload

Output Parameters

Expand all
appointmentcopay string Detailed information about the copay for this appointment. Gives more detail than the COPAY field. Note: this information is not yet available in all practices, we are rolling this out slowly.
appointmentid string Appointment ID of the booked appointment
appointmentstatus string The athenaNet appointment status. There are several possible statuses. x=cancelled. f=future. (It can include appointments where were never checked in, even if the appointment date is in the past. It is up to a practice to cancel appointments as a no show when appropriate to do so.) o=open. 2=checked in. 3=checked out. 4=charge entered (i.e. a past appointment).
appointmenttype string The practice-friendly (not patient friendly) name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
appointmenttypeid string This is the ID for the appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
claims array As detailed in /claims, if requested.
copay string Expected copay for this appointment. Based on the appointment type, the patient's primary insurance, and any copays collected. To see the amounts used in this calculated value, see the APPOINTMENTCOPAY fields.
date string The appointment date.
departmentid string
duration integer In minutes
frozenyn string If true, this appointment slot is frozen
hl7providerid integer This is the raw provider ID that should be used ONLY if using this appointment in conjunction with an HL7 message and with athenahealth's prior guidance. It is only available in some situations.
patient string As detailed in /patients, if requested.
patientappointmenttypename string The patient-friendly name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
patientid string The athenaNet patient ID for this appointment
providerid string
referringproviderid integer The referring provider ID.
renderingproviderid integer The rendering provider ID.
rescheduledappointmentid string When an appointment is rescheduled, this is the ID of the replacement appointment.
startcheckin string The timestamp when the appointment started the check in process. If this is set while an appointment is still in status 'f', it means that the check-in process has begun but is not yet completed.
starttime string As HH:MM (where HH is the 0-23 hour and MM is the minute). This time is local to the department.
stopcheckin string The timestamp when the check-in process was finished for this appointment.
supervisingproviderid integer The supervising provider ID.
urgentyn string Urgent flag for the appointment.
useexpectedprocedurecodes array An array of expected procedure codes attached to this appointment.
Example Code

Gets the appointment id tied to the confirmation hash in the appointment confirmation email

GET
/v1/{practiceid}/appointments/getappointmentidbyhash/{messagehash}
Gets the appointment id tied to the confirmation hash
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
messagehash string messagehash

Output Parameters

Expand all
appointmentid integer The Appointment ID.
Example Code

Retrieve athenaone telehealth invite url.

GET
/v1/{practiceid}/appointments/{appointmentid}/nativeathenatelehealthroom
Retrieve athenaone telehealth invite url.
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
appointmentid integer appointmentid

Output Parameters

Expand all
appointmentid string The athenaNet Appointment ID.
jointoken string The appointment join token.
patienturl string The patient native athenaTelehealth appointment link.
Example Code

Get list of changes in appointment slots based on subscribed events

GET
/v1/{practiceid}/appointments/changed
Retrieves the list of changes in appointments or appointment slots Note: This endpoint may rely on specific settings to be enabled in athenaNet Production to function properly that are not required in other environments. Please see Permissioned Rollout of APIs for more information if you are experiencing issues.
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
leaveunprocessed boolean For testing purposes, do not mark records as processed.
patientid array Patient ID. Multiple Patient IDs are allowed, either comma separated or with multiple values.
showcopay boolean Return copay information with the appointment data.
showinsurance boolean Include patient insurance information. Shows insurance packages for the appointment if any are selected, and all patient packages otherwise.
showexpectedprocedurecodes boolean Show the expected procedurecodes.
showpatientdetail boolean Include patient information for each patient associated with an appointment.
ignorerestrictions boolean When showing patient detail for appointments, the patient information for patients with record restrictions and blocked patients will not be shown. Setting this flag to true will show that information for those patients.
departmentid array Department ID. Multiple departments are allowed, either comma separated or with multiple values.
providerid array Provider ID. Multiple providers are allowed using comma separated values.
showprocessedenddatetime string See showprocessedstartdatetime.
showclaimdetail boolean Include claim information, if available, associated with an appointment.
showremindercalldetail boolean Include all remindercall related results, if available, associated with an appointment.
showprocessedstartdatetime string Show already processed changes. This will show changes that you previously retrieved at some point after this datetime mm/dd/yyyy hh24:mi:ss (Eastern). Can be used to refetch data if there was an error, such as a timeout, and records are marked as already retrieved. This is intended to be used with showprocessedenddatetime and for a short period of time only. Also note that all messages will eventually be deleted.
limit integer Number of entries to return (default 1000, max 10000)Please note that this endpoint has a different default and max than normal.
offset integer Starting point of entries; 0-indexed

Output Parameters

Expand all
appointmentconfirmationid string If there is an appointment confirmation result for this appointment, the numeric ID (global to athenaNet).
appointmentconfirmationname string If there is an appointment confirmation result for this appointment, the name (global to athenaNet).
appointmentcopay string Detailed information about the copay for this appointment. Gives more detail than the COPAY field. Note: this information is not yet available in all practices, we are rolling this out slowly.
appointmentid string Appointment ID of the booked appointment
appointmentnotes array An array of appointment notes for this appointment.
appointmentstatus string The athenaNet appointment status. There are several possible statuses. x=cancelled. f=future. (It can include appointments where were never checked in, even if the appointment date is in the past. It is up to a practice to cancel appointments as a no show when appropriate to do so.) o=open. 2=checked in. 3=checked out. 4=charge entered (i.e. a past appointment).
appointmenttype string The practice-friendly (not patient friendly) name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
appointmenttypeid string This is the ID for the appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
cancelledby string If the appointment has been cancelled, the username who cancelled the appointment.
cancelleddatetime string The time (mm/dd/yyyy hh24:mi:ss; Eastern time) that this appointment was cancelled (if cancelled)
cancelreasonid string If the appointment was cancelled, the numeric ID (local to the practice) for the cancel reason.
cancelreasonname string If the appointment was cancelled, the name (local to the practice) for the cancel reason.
cancelreasonnoshow string If the appointment was cancelled, if the cancel reason is marked as a no show reason.
cancelreasonslotavailable string If the appointment was cancelled, if the cancel reason is marked as a slot available reason.
chargeentrynotrequired string This field will tell if an appointment has been marked as not requiring change entry.
chargeentrynotrequiredreason string This field will give the reason that an appointment has been marked as not requiring charge entry.
checkindatetime string The time (mm/dd/yyyy hh24:mi:ss) that the appointment was checked in.
checkoutdatetime string The time (mm/dd/yyyy hh24:mi:ss) that the appointment was checked out.
claims array As detailed in /claims, if requested.
coordinatorenterpriseyn string If true, the appointment was booked through athenaCoordinator Enterprise.
copay string Expected copay for this appointment. Based on the appointment type, the patient's primary insurance, and any copays collected. To see the amounts used in this calculated value, see the APPOINTMENTCOPAY fields.
date string The appointment date.
departmentid string
duration integer In minutes
encounterid string The encounter id associated with this appointment, useful for certain other calls. Only present for appointments with Clinicals that have been checked in.
encounterstatus string The status of this patient in the encounter (READYFORSTAFF, WITHSTAFF, READFORPROVIDER, CHECKEDOUT). Only present for appointments with Clinicals that have been checked in.
frozenyn string If true, this appointment slot is frozen
hl7providerid integer This is the raw provider ID that should be used ONLY if using this appointment in conjunction with an HL7 message and with athenahealth's prior guidance. It is only available in some situations.
insurances array List of active patient insurance packages. Only shown for single or multiple booked appointments if SHOWINSURANCE is set.
lastmodified string The date/time when the appointment was last modified. Note: It may be possible for the lastmodified field to be updated without any other field in the API call being changed. This occurs when appointment fields not included in the API output are updated.
lastmodifiedby string The user who last modified the appointment.
patient string See /patients for details
patientappointmenttypename string The patient-friendly name for this appointment type. Note that this may not be the same as the booked appointment because of "generic" slots.
patientid string The athenaNet patient ID for this appointment
patientlocationid string The location of the patient. See /patientlocation for practice list. Only present for appointments with Clinicals that have been checked in.
providerid string
referringproviderid integer The referring provider ID.
reminderdetails array Detailed ReminderCall information made for this appointment.
renderingproviderid integer The rendering provider ID.
rescheduledappointmentid string When an appointment is rescheduled, this is the ID of the replacement appointment.
scheduledby string The username who scheduled the appointment.
scheduleddatetime string The time (mm/dd/yyyy hh24:mi:ss; Eastern time) that this appointment was scheduled.
startcheckin string The timestamp when the appointment started the check in process. If this is set while an appointment is still in status 'f', it means that the check-in process has begun but is not yet completed.
startcheckoutdatetime string The time (mm/dd/yyyy hh24:mi:ss) that the appointment check-out was started.
starttime string As HH:MM (where HH is the 0-23 hour and MM is the minute). This time is local to the department.
stopcheckin string The timestamp when the check-in process was finished for this appointment.
stopexamdatetime string The time (mm/dd/yyyy hh24:mi:ss) that the exam was completed.
stopintakedatetime string The time (mm/dd/yyyy hh24:mi:ss) that the intake process was completed.
suggestedoverbooking string High risk score for Smart Scheduling
supervisingproviderid integer The supervising provider ID.
templateappointmentid string The original appointment ID. This is useful if an appointment has been cancelled and you want to find the original ID.
templateappointmenttypeid string The original appointment type for this slot. This can change for generic appointments.
urgentyn string Urgent flag for the appointment.
useexpectedprocedurecodes array An array of expected procedure codes attached to this appointment.
Example Code

Get list of appointment slot change subscription(s)

GET
/v1/{practiceid}/appointments/changed/subscription
Retrieves the list of events appointment slots which are modified
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
includesuggestedoverbooking boolean If this is set, we will include the UpdateSuggestedOverbooking event as if it is one of the default events. Otherwise we will ignore that it exists.
includeremindercall boolean If this is set, we will include the UpdateRemiderCall event as if it is one of the default events. Otherwise we will ignore that it exists.

Output Parameters

Expand all
departmentids array List of Departmentids subscribed
status string Will return one of following statuses: ACTIVE, INACTIVE, or PARTIAL. The PARTIAL status means that not all events are subscribed to. In the event of a problem, UNKNOWN may be returned.
subscriptions array List of events you are subscribed to.
Example Code

Subscribe to all/specific change events for appointment slots

POST
/v1/{practiceid}/appointments/changed/subscription
Subscribes for changed appointment slots events
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
Content-Type string Content type of the payload

Output Parameters

Expand all
success string Returns if the call to manipulate subscriptions for appointments was successful.
Example Code

Unsubscribe to all/specific change events for appointment slots

DELETE
/v1/{practiceid}/appointments/changed/subscription
Delete a specific event which is no longer required
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid
eventname string By default, you are unsubscribed from all possible events. If you only wish to unsubscribe from an individual event, pass the event name with this argument.
includesuggestedoverbooking boolean If this is set, we will include the UpdateSuggestedOverbooking event as if it is one of the default events. Otherwise we will ignore that it exists.
includeremindercall boolean If this is set, we will include the UpdateRemiderCall event as if it is one of the default events. Otherwise we will ignore that it exists.

Output Parameters

Expand all
success string Returns if the call to manipulate subscriptions for appointments was successful.
Example Code

Get list of appointment slot change events to which you can subscribe

GET
/v1/{practiceid}/appointments/changed/subscription/events
Retrieves list of events for appointments or an appointment slots
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit
Try in Postman

Input Parameters

Expand all

required

practiceid integer practiceid

Output Parameters

Expand all
status string Will return one of following statuses: ACTIVE, INACTIVE, or PARTIAL. The PARTIAL status means that not all events are subscribed to. In the event of a problem, UNKNOWN may be returned.
subscriptions array List of events you are subscribed to.
Example Code