API Tools

The API tools Developer Hub

Welcome to the API tools developer hub. You'll find comprehensive guides and documentation to help you start working with API tools as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Argonaut Scheduling

Argonaut Scheduling IG (Release 1.0.0) HomePage


The Argonaut Scheduling Project is a vendor agnostic specification providing FHIR RESTful APIs and guidance for access to and booking of appointments for patients by both patient and practitioner end users. This specification is based on FHIR Version 3.0.1 and specifically the Scheduling and Appointment resources.

These requirements were developed and defined by the Argonaut pilot implementations and through the HL7 Connectathons.


Patient Based Scheduling

For a detailed description of the use cases and workflow see the Patient Scheduling Use Cases page.

  1. Patient based scheduling enables a patient to use an organization’s on-line service (“patient portal”) or a third-party application to search for available appointments. This scenario when patient is a new patient (“open-scheduling” through a third party application) or an existing patient (patient portal or third-party application). Only those procedures/specialties/services based on the following inputs will be available:
    • practitioner
    • available times
    • location
    • specialty
    • set of common visit types.
  2. Patient registers and provides coverage information through a patient portal or a third-party application.
  3. Patient books an appointment through a patient portal or a third-party application.
  4. Patient cancels an appointment through a patient portal or a third-party application.
  5. Patient retrieves their scheduled appointments through a patient portal or a third-party application.

Provider based Scheduling

For a detailed description of the use cases and workflow see the Provider Scheduling Use Cases page.

Note that in this guide “provider” = individual, organization or healthcare service.

  1. Provider scheduling between organizations on behalf of a patient
    1. searches for available appointment times for a service or procedure
    2. Includes scenarios when patient is a new patient or an existing patient.
    3. Only those procedures/specialties/services based on the following inputs will be available:
      • practitioner
      • available times
      • location
      • specialty
      • set of common visit types
    4. books an appointment
    5. cancels an appointment
    6. Exchange of coverage and medical history
  2. Provider retrieves their existing appointments for all patients


In FHIR, booking an appointment typically includes two main actors: the FHIR Server serving as the EHR scheduler and a Client as a scheduling application. For the patient based scheduling, the actors are depicted in figure 1 below. Note that for the 3rd Party Application the scheduling application is both server for the end user application and a client of the FHIR Server. In the patient portal use case the the end user application interacts directly with the FHIR Server.

Actors for Patient Based Scheduling.

For the provider based scheduling, the actors are depicted in the figure below. The referring provider’s scheduling application is the client and may schedule with or without patient input.

Actors for Provider Based Scheduling.

Assumptions and Preconditions

  1. A third party patient scheduling application may ‘pre-fetch’ open slots and create appointments or it may fetch open appointments in real time.
  2. System level trust exists between a scheduling server and am external provider system.
    • Supports the use case 5 defined for Phase 1 of the Argonaut Project.
    • One solution is to use access FHIR resources by requesting access tokens from OAuth 2.0 compliant authorization servers using SMART Backend Services.
    • it is assumed that consent is managed elsewhere.
  3. User level login and trust exists between the scheduling service and a third party application.
    • An client application has been authorized by the health system.
    • Uses SMART on FHIR authorization for apps that connect to EHR data.
    • If the patient is successfully registered via a third-party application or logged into an EHR’s patient portal, the patient ID is returned or known.
    • ‘Open-scheduling’: Authorized applications can search for available appointments without Server having to “know” the patient.
      • Later on in interaction a “patient level authorization” in order to create a new account and complete the appointment will be required. The technical details for this are out of scope for this project.
      • Alternate approaches are out of scope for this project.
  4. Rescheduling and appointment is a two step process of canceling and rebooking.
  5. US Core Profiles are supported
  6. US Core General Guidance and conventions apply to this guide.


For general security consideration refer to the Security section in the US Core Implementation Guide. See the Assumptions section above for a discussion of login and trust.

Future Scope

Throughout the development of the Argonaut Scheduling Guide several additional important items were reviewed for robust scheduling implementations. This page summarizes items under development, or things that should be considered for future efforts.

  1. “Discovery Operation”
    1. This operation would asks the key questions 1. What Service(/specialty/provider) are bookable? Off-line exchanges (e.g., a spreadsheet) are typically used to exchange this information. This information is Static and is easy to prefetch Amending can be used as a filter when searching for appointment availability reducing the burden on server. Consumer Facing apps can use this information to create appointments from slots. In the future the Provider Directory (i.e., “common catalog”) can supply much of this key services information. But in our initial scope, only those specialties/services based on the “simple” inputs 1. available times, location, specialty1. will be available.
  2. Additional input requirements
    1. As stated above, in our initial scope, only those specialties/services based on a limited set of inputs are considered. Additional patient input and more advanced conflict checking has been deferred. Information like additional patient demographics, chief complaint/indication and other details can help with identifying the available appointments.

    2. For example an operation could precede the search for appointment availability to discover what inputs are needed for the service. This operation would return a questionnaire to be filled out by the end user and submitted with the appointment availability operation. Alternatively, an operation could return an OperationOutcome resource informing the client that information is needed and a questionnaire to be completed first.

  3. Amending an appointment or patient information by an end user
    1. Need to establish what if anything the consumer can update.
  4. Scheduling Requests
    1. Appointment Requests are “everything that is not covered by an appointment availability operation”
    2. Patient scheduling scenario 1. where system could not find appointment and need to figure out what wanted or needed. This may sometimes results in out of sync, out of band ( call-back) responses.
    3. May need have a separate interaction that users can just submit the request.
  5. Best Practices
    1. Add a section prescribing best practices for technical operations. Such as a check list of steps ( Client SHALL verify successful cancellation prior to rebooking ).
  6. Prior approvals including preauthorizations
  7. Scheduling physical (rooms, modalities, etc.) resources
  8. Initiating Transitions of Care
  9. Language support
  10. Multimedia support
  11. Estimated out of pocket patient costs
  12. Provider based scheduling within an organization

Updated about a month ago

Argonaut Scheduling

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.