This page is part of the Argonaut Scheduling Implementation Guide (v1.0.0: Release) based on FHIR R3. This is the current published version. For a full list of available versions, see the Directory of published versions
Appointment Availability Operation
OPERATION: Appointment Availability Operation
The official URL for this operation definition is:
http://fhir.org/guides/argonaut-scheduling/OperationDefinition/appointment-find
Searches for availability for a future appointment(s) within a time period of defined by date range input parameters. If neither a start or end date is given then the maximum period as defined by local business rules and starting from when the operation was transacted will be used. Other input parameter further refine the search and include practitioner references, specialties, visit type, locations, and patient information. From these criteria, a system determines which schedulable resources ( e.g., people, rooms, equiibment) are needed for the visit, and provides time slots where all required resources are available.
URL: [base]/Appointment/$find
Parameters
Use | Name | Cardinality | Type | Binding | Documentation |
IN | start | 1..1 | dateTime |
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). |
|
IN | end | 1..1 | dateTime |
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). |
|
IN | specialty | 0..* | string (token) | http://fhir.org/guides/argonaut-scheduling/ValueSet/specialty (Extensible) |
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 |
IN | visit-type | 0..* | string (token) | http://fhir.org/guides/argonaut-scheduling/ValueSet/visit-type (Extensible) |
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 |
IN | practitioner | 0..* | 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). |
|
IN | organization | 0..* | 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). |
|
IN | location-string | 0..* | 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 |
|
IN | location-reference | 0..* | uri |
A Location reference when performing an operation where the Location resource |
|
IN | patient-reference | 0..* | uri |
A Patient reference when performing an operation where the Patient resource |
|
IN | patient-resource | 0..* | Patient (US Core Patient Profile) |
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 |
|
IN | coverage | 0..* | Coverage (Argonaut Coverage Profile) |
This parameter uses the Coverage type and is constrained to the the Argonaut Coverage Profile. It provides insurance information for scheduling an appointment and or registering a patient. Do not transmit Coverage resource elements that require the Patient resource id if it is not known. If multiple coverage resources are listed, the response will contain appointments which is joint match for all coverages and patients - i.e., a group appointment. |
|
IN | reason | 0..* | string (token) | http://hl7.org/fhir/ValueSet/condition-code (Preferred) |
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 |
OUT | return | 0..1 | Bundle (Argonaut Appointment Bundle Profile) |
An Argonaut Appointment Bundle Profile of type |
- For input parameters that are codes, the simple FHIR token search parameter type is used instead of the complex
Coding
datatype. Also, the simpleuri
datatype is used instead of the complexReference
datatype for resources references. This allows either the 'GET' or the 'POST' syntax to be used to initiate the interaction in many cases. Examples of both are shown below. - If more than one actor type is present, the response SHOULD contain appointments with all of these actors (i.e, this is a logical 'AND'). If an actor type is repeated the response SHOULD contain appointments with any of these actors and SHOULD be interpreted as the order of preference (i.e. this is a logical 'OR' and does not drive a joint appointment with multiple practitioners. locations or organizations). Ultimately the server is responsible for determining the first/best available appointment options to return.
- References can be to an absolute URL, but servers only perform operations on their own resources.
- To set the upper limit on the total number of available appointment options to return use the standard
_count
search parameter. See the examples below for how this is implemented.
Using Both GET
and POST
Syntax the operation can be invoked as follows:
GET [base]/Appointment/$find?{parameters}&?{_count}
POST [base]/Appointment/$find?{_count}
Examples
Scenario 1a:
Use the operation to fetch a maximum of the soonest 3 open appointments available within the next 2 days for Dr Y at the Napa location.
Request using GET
GET [base]/Appointment/$find?start=2017-07-15T20:00:00Z&end=2017-07-17T20:00:00Z&provider=Practitioner/dr-y&location=Napa&_count=3
Request using POST
POST [base]/Appointment/$find&_count=3
Request body
{
"resourceType": "Parameters",
"parameter": [
{
"name": "start",
"valueDateTime" : "2017-07-15T20:00:00Z"
},
{
"name": "end",
"valueDateTime" : "2017-07-17T20:00:00Z"
},
{
"name": "provider",
"valueUri": ["Practitioner/dr-y"]
}
},
{
"name": "location",
"valueString": ["Napa"]
}
]
}
Response
HTTP/1.1 200 OK
[other headers]
Response body
{
"resourceType": "Bundle",
"id": "hal-dr-y-appts",
"type": "searchset",
"total": 3,
"entry": [{
"fullUrl": "http://server/path/Appointment/proposed-appt-1",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-1",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-2",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-2",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-3",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-3",
.. snip ...
},
"fullUrl": "http://server/path/OperationOutcome/oo-for-dr-y-appts",
"resource": {
"resourceType": "OperationOutcome",
"id": "oo-for-dr-y-appts",
.. snip ...
}
]
}
appointment-find1b.md
Scenario 1b:
Use the operation to fetch a maximum of the soonest 3 open appointments available within the next 2 days for the requested service at the Napa location.
Request using GET
[base]/Appointment/$find?start=2017-07-15T20:00:00Z&end=2017-07-17T20:00:00Z&service-type=http://snomed.info/sct|708175003
&appt-type=http://fhir.org/guides/argonaut-scheduling/CodeSystem/appt-type|urgent&location=Napa
Request using POST
POST [base]/Appointment/$find&_count=3
Request body
{
"resourceType": "Parameters",
"parameter": [
{
"name": "start",
"valueDateTime" : "2017-07-15T20:00:00Z"
},
{
"name": "end",
"valueDateTime" : "2017-07-17T20:00:00Z"
},
{
"name": "appt-type",
"valueString": ["http://fhir.org/guides/argonaut-scheduling/CodeSystem/appt-type|urgent"]
},
{
"name": "service-type",
"valueString": ["http://snomed.info/sct|708175003"]
},
{
"name": "location",
"valueString": ["Napa"]
}
]
}
Response
HTTP/1.1 200 OK
[other headers]
Response body
{
"resourceType": "Bundle",
"id": "hal-imaging-appts",
"type": "searchset",
"total": 3,
"entry": [{
"fullUrl": "http://server/path/Appointment/proposed-appt-1",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-1",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-2",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-2",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-3",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-3",
.. snip ...
},
"fullUrl": "http://server/path/OperationOutcome/oo-for-imaging-appts",
"resource": {
"resourceType": "OperationOutcome",
"id": "oo-for-imaging-appts",
.. snip ...
}
]
}
appointment-find2a.md
Scenario 2a:
Use the operation to fetch all of Dr Y’s open appointments for the Napa location for the next month.
Request using GET
GET [base]/Appointment/$find?start=2017-07-15T20:00:00Z&end=2017-08-17T20:00:00Z&
provider=Practitioner/dr-y&location=Napa
Request using POST
POST [base]/Appointment/$find&_count=3
Request body
{
"resourceType": "Parameters",
"parameter": [
{
"name": "start",
"valueDateTime" : "2017-07-15T20:00:00Z"
},
{
"name": "end",
"valueDateTime" : "2017-07-17T20:00:00Z"
},
{
"name": "provider",
"valueUri": ["Practitioner/dr-y"]
},
{
"name": "location",
"valueString": ["Napa"]
}
]
}
Response
HTTP/1.1 200 OK
[other headers]
Response body
{
"resourceType": "Bundle",
"id": "prefetch-dr-y-appts",
"type": "searchset",
"total": <n>, // n = All the open Napa appts
"entry": [{
"fullUrl": "http://server/path/Appointment/proposed-appt-1",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-1",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-2",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-2",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-3",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-3",
.. snip ...
},
... snip ...
"fullUrl": "http://server/path/OperationOutcome/oo-for-dr-y-appts",
"resource": {
"resourceType": "OperationOutcome",
"id": "oo-for-dr-y-appts",
... snip ...
}
]
}
appointment-find2b.md
Scenario 2b:
Use the operation to fetch all open appointments for dermatologists in Napa location for the next month.
Request using GET
GET [base]/Appointment/$find?start=2017-07-15T20:00:00Z&end=2017-08-17T20:00:00Z&appt-type=http://hl7.org/fhir/v2/0276|ROUTINE&
specialty=http://snomed.info/sct|394582007&location=Napa
Request using POST
POST [base]/Appointment/$find&_count=3
Request body
{
"resourceType": "Parameters",
"parameter": [
{
"name": "start",
"valueDateTime" : "2017-07-15T20:00:00Z"
},
{
"name": "end",
"valueDateTime" : "2017-07-17T20:00:00Z"
},
{
"name": "appt-type",
"valueString": ["http://hl7.org/fhir/v2/0276|ROUTINE"]
},
{
"name": "specialty",
"valueString": ["http://snomed.info/sct|394582007"]
},
{
"name": "location",
"valueString": ["Napa"]
}
]
}
Response
HTTP/1.1 200 OK
[other headers]
Response body
{
"resourceType": "Bundle",
"id": "prefetch-derm-appts",
"type": "searchset",
"total": 3,
"entry": [{
"fullUrl": "http://server/path/Appointment/proposed-appt-1",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-1",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-2",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-2",
.. snip ...
},
"fullUrl": "http://server/path/Appointment/proposed-appt-3",
"resource": {
"resourceType": "Appointment",
"id": "proposed-appt-3",
.. snip ...
},
"fullUrl": "http://server/path/OperationOutcome/oo-for-derm-appts",
"resource": {
"resourceType": "OperationOutcome",
"id": "oo-for-derm-appts",
.. snip ...
}
]
}