Find Appointment Slot

4min

A key step in the Appointment Scheduling flow is finding an available appointment slot. Based on the parameters in the Find Appointment Slot request, possible Appointment times are returned where all required "assets" are available. 
Interaction
Finding the available appointment slots can be done by sending a POST request with the FHIR $find operation to the Appointment endpoint:
https://api.<region>.founda.com/1/health/organizations/<org-x>/fhir/4/Appointment/$find
Where <region> should be defined according to the different Founda regions﻿ and <org-x> should be replaced with the Healthcare Provider's organization ID that you are integrated with. 
The POST request should contain the required assets in the body according the Parameters table. 
The response contains a Bundle with a search set of proposed appointment times, matching the amount that was queried for in the body. 
Profile
Founda adheres to recognized standards (IHE, HL7 FHIR) to ensure compatibility and harmonization among diverse systems. If there is a profile available for an interaction, it is recommended and preferred to follow the prescribed transactions.
The Find Appointment Slot interaction with the Founda Platform is based on the IHE FHIR Scheduling profile's ITI-114 transaction.
Parameters
These input parameters determine which assets are needed to be able to schedule the visit. The $find operation returns a set of possible Appointment times where all required assets are available.  
Parameter
Type
Required
Documentation
start
dateTime
Y
The period of time that should be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no start date is provided, all available appointments prior to the end date are in scope (subject to limits imposed by local business rules).
end
dateTime
Y
The period of time that should be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no end date is provided, all available appointments after the start date are in scope (subject to limits imposed by local business rules).
specialty
string
﻿
The code for which specialty is requested for the appointment. ( e.g., 'Dermatology'). If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors). Each parameter value SHALL contain both the system property and the code property for a code using the general syntax specialty=[system]|[code]. 
visit-type
string
﻿
The code for one of the common appointment visit types for scheduling. ( e.g.,'Echocardiography' or 'Well child visit' ). This list of visit types is extensible and implementers may choose to add there own codes. If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these services (i.e. this does not drive joint appointment with multiple services). Each parameter value SHALL contain both the system property and the code property for a code using the general syntax service-type=[system]|[code]. 
practitioner
uri
﻿
The Practitioner reference when performing a provider based query. This is a reference to a FHIR Practitioner resource, e.g. 'Practitioner/123'. If multiple practitioner references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors).
organization
uri
﻿
The Organization reference when performing a provider based query. This is a reference to a FHIR Organization resource, e.g. 'Organization/abc'. If multiple organization references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors).
location-string
string
﻿
A (part of the) address of the location of interest. (e.g., zip codes, city or state). This string parameter is interpreted as a String search parameter and covers the string type elements in the Address datatype. If multiple locations are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)
location-reference
uri
﻿
A Location reference when performing an operation where the Location resource id is known. If multiple location references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)
patient-reference
uri
﻿
A Patient reference when performing an operation where the Patient resource id is known. Patient resources include demographics and patient preferences that may be important for availaiblilty searches. If multiple patient references are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment.
patient-resource
Patient
﻿
This parameter uses the Patient resource type instead of a simple reference because the patient record may not exist when performing availablity searches. (If the Patient resource id is known, use the patient-reference parameter instead.) It based on the US Core Patient Profile and includes demographics and patient preferences that may be important for availaiblilty searches. If the appointment is for a new patient, the patient record should not be created until just before booking an appointment. If multiple patient resources are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment.
reason
string
﻿
A clinical sign, symptom, diagnosis or health concern that this appointment is intended to treat. This may is used in conjunction with the specialty to determine which schedulable resources are needed for the visit. For example, for an orthopedics appointment, the reason may drive whether a hip specialist or knee specialist is preferred. Each parameter value SHALL contain both the system property and the code property for a code using the general syntax specialty=[system]|[code]. See the examples below for how this is implemented.
Example API call
Curl
curl --location 'https://api.eu.founda.com/1/health/organizations/org-4c5739ba994d4ce9b5255d3f84a2d367/fhir/4/Appointment/$find' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ory_at_j3f3k53SVP4B8FUoQij99xSXG0yTisqdO6n89IE_8ZU.1jzkaQAuUq_tj79lJQfczRubXQ4gTqLO4XbvKWVEmQM' \
--data '    {
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "start",
          "valueDateTime" : "2017-07-15T20:00:00Z"
        },
        {
          "name": "end",
            "valueDateTime" : "2017-07-17T20:00:00Z"
        },
        {
          "name": "provider",
          "valueUri": ["Practitioner/2079"]
          }
        },
        {
          "name": "location",
          "valueString": ["South Wing, second floor"]
        }
    ]
    }'
curl --location 'https://api.eu.founda.com/1/health/organizations/org-4c5739ba994d4ce9b5255d3f84a2d367/fhir/4/Appointment/$find' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ory_at_j3f3k53SVP4B8FUoQij99xSXG0yTisqdO6n89IE_8ZU.1jzkaQAuUq_tj79lJQfczRubXQ4gTqLO4XbvKWVEmQM' \
--data '    {
      "resourceType": "Parameters",
      "parameter": [
        {
          "name": "start",
          "valueDateTime" : "2017-07-15T20:00:00Z"
        },
        {
          "name": "end",
            "valueDateTime" : "2017-07-17T20:00:00Z"
        },
        {
          "name": "provider",
          "valueUri": ["Practitioner/2079"]
          }
        },
        {
          "name": "location",
          "valueString": ["South Wing, second floor"]
        }
    ]
    }'
﻿
﻿

Parameter	Type	Required	Documentation
start	dateTime	Y	The period of time that should be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no start date is provided, all available appointments prior to the end date are in scope (subject to limits imposed by local business rules).
end	dateTime	Y	The period of time that should be checked for appointment availability.- e.g., look for all available appointments in a certain date range. If no end date is provided, all available appointments after the start date are in scope (subject to limits imposed by local business rules).
specialty	string		The code for which specialty is requested for the appointment. ( e.g., 'Dermatology'). If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors). Each parameter value SHALL contain both the system property and the code property for a code using the general syntax specialty=[system]\|[code].
visit-type	string		The code for one of the common appointment visit types for scheduling. ( e.g.,'Echocardiography' or 'Well child visit' ). This list of visit types is extensible and implementers may choose to add there own codes. If multiple codes are listed, the order of the codes will interpreted as the order of preference. The response will contain appointments with any of these services (i.e. this does not drive joint appointment with multiple services). Each parameter value SHALL contain both the system property and the code property for a code using the general syntax service-type=[system]\|[code].
practitioner	uri		The Practitioner reference when performing a provider based query. This is a reference to a FHIR Practitioner resource, e.g. 'Practitioner/123'. If multiple practitioner references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors).
organization	uri		The Organization reference when performing a provider based query. This is a reference to a FHIR Organization resource, e.g. 'Organization/abc'. If multiple organization references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple actors).
location-string	string		A (part of the) address of the location of interest. (e.g., zip codes, city or state). This string parameter is interpreted as a String search parameter and covers the string type elements in the Address datatype. If multiple locations are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)
location-reference	uri		A Location reference when performing an operation where the Location resource id is known. If multiple location references are listed, the order will interpreted as the order of preference. The response will contain appointments with any of these actors (i.e. this does not drive joint appointment with multiple locations)
patient-reference	uri		A Patient reference when performing an operation where the Patient resource id is known. Patient resources include demographics and patient preferences that may be important for availaiblilty searches. If multiple patient references are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment.
patient-resource	Patient		This parameter uses the Patient resource type instead of a simple reference because the patient record may not exist when performing availablity searches. (If the Patient resource id is known, use the patient-reference parameter instead.) It based on the US Core Patient Profile and includes demographics and patient preferences that may be important for availaiblilty searches. If the appointment is for a new patient, the patient record should not be created until just before booking an appointment. If multiple patient resources are listed, the response will contain appointments which is joint match for all patients - i.e., a group appointment.
reason	string		A clinical sign, symptom, diagnosis or health concern that this appointment is intended to treat. This may is used in conjunction with the specialty to determine which schedulable resources are needed for the visit. For example, for an orthopedics appointment, the reason may drive whether a hip specialist or knee specialist is preferred. Each parameter value SHALL contain both the system property and the code property for a code using the general syntax specialty=[system]\|[code]. See the examples below for how this is implemented.

Updated 19 Oct 2023

Did this page help you?

Retrieve Appointment

Book Appointment