Find Available Time Slots for an Appointment

When a call center agent wants to schedule an appointment, the first step is to find the available time slots for providers who match the patient’s needs. The call center agent gathers selection criteria and then initiates a search to obtain the available slots for providers who match the criteria.

Type: Controller
Verb: POST
Default URL Path: <base-url>/Slot/_search
Content-Type (Header): application/x-www-form-urlencoded

Your Base URL is configured in Setup > Appointment Scheduling.

All communications with the external system use the FHIR R4 standard.

Request Body

1schedule:Schedule.actor:Practitioner.identifier=http://hl7.org/fhir/sid/us-npi|323,434,567,342,234,224,423
2&schedule:Schedule.actor:Location._id=epic|555,epic|123,allscripts|124,allscripts|221,cerner|222,cerner|223,athena|331,athena|332
3&schedule:Schedule.actor:Practitioner._id=epic|2342342,&start=ge2020-10-10
4&start=le2021-03-31&appointment-type=epic|ROUTINE,epic|ROUTINE,cerner|RTN,athena|REGULAR
5&service-type=epic|H999,cerner|E100,athena|C200,allscripts|A300
6&status=free
7&_include=Slot:schedule
8&_sort=start

The request payload is sent as single line. It is listed here in separate lines for readability.

Note

Multiple Source Systems

If you are working with more than one source system, the Location._id gets the source system name and ID in pipe-delimited pairs, separated by commas, like this:

1schedule:Schedule.actor:Location._id=epic|1404774,cerner|1476569

For a single source system, the Location._id is the ID only, like this:

1schedule:Schedule.actor:Location._id=1404774,1476569

Response Codes

200: Success
400: Bad request
401: Unauthorized
5xx: Server error

Response Body

To map slots, resource, resourceType, id, schedule, actor, start, and end are required in the FHIR response.
Response is a map keyed by CareProvider.careProviderId to give all available slots within the start/end range for a single practitioner+facility pair that can fulfill an appointment for the serviceTypeCode+appointmentTypeCode.
If a practitioner+facility pair is not found in the source system, the provider is ignored and nothing is returned for that careProviderId. If a practitioner+facility pair does not have availability that matches the slot range and codes, the careProviderId is returned without any slots.
By default, the list of returned slots for each provider is sorted by date/time in ascending order.
The sourceSlotId for a slot is the ID of a time slot in the source system for a care provider (eg. practitioner+facility) that can fulfill a specific serviceTypeCode+appointmentTypeCode. Given this ID during appointment booking, the source system is able to identify the practitioner, facility, time slot, service type and appointment type.

1{
2"resourceType": "Bundle",
3"id": "",
4"meta": {"lastUpdated":},
5"type": "searchset",
6"total": n,
7"entry": [    
8    "fullUrl" : ""    ,
9    "resource" : {     
10        "resourceType" : "Slot",    
11        "id" : "<String>",
12        "identifier" : [{ Identifier }],     
13        "serviceCategory" : [{ CodeableConcept }],     
14        "serviceType" : [{ CodeableConcept }],     
15        "specialty" : [{ CodeableConcept }],     
16        "appointmentType" : { CodeableConcept },    
17        "schedule" : { Reference(Schedule) }, //expects to get actor in this object
18        "status" : "<code>",    
19        "start" : "<instant>",    
20        "end" : "<instant>",    
21        "overbooked" : <boolean>,    
22        "comment" : "<string>"    
23     } 
24    ]
25}

Error Response for Multiple Source Systems

1{
2      "resourceType": "Bundle",
3      .......
4      "entry": [
5      {
6      "fullUrl": "http://hapi.fhir.org/baseR4/Slot/1939809",
7      "resource": {
8      "resourceType": "Slot",
9      .......
10      },
11      "search": {"mode": "match"}
12      },
13      {
14      "fullUrl": "http://hapi.fhir.org/baseR4/Schedule/1939822",
15      "resource": {
16      "resourceType": "Schedule",
17      "id": "1939822",
18      .....
19      },
20      "search": {"mode": "include"}
21      },
22      { //If the targeting system is FHIR R4, you get OperationOutcome resource as error. Pass it back with one of the elements in "Bundle.entry" and "extension" to identify the target system.
23      "resourceType": "OperationOutcome",
24      ....
25      "extension" : [{
26      "url" : "https://fhir-ehr-code.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Slot/_search33",
27      "value" : "cerner"
28      }]
29      "issue": [ {
30      "severity": "error",
31      "code": "processing",
32      "diagnostics": "Invalid request: The FHIR endpoint on this server does not know how to handle GET operation[Slot/_search33] with parameters [[_include, _pretty, schedule:Schedule.actor:Practitioner.identifier, appointment-type, service-type, schedule:Schedule.actor:Practitioner._id, schedule:Schedule.actor:Location._id]]"
33      }
34      ]
35      }
36      ]
37      }

Identifier

1{
2  "use" : "<code>", // usual | official | temp | secondary | old (If known)
3  "type" : { CodeableConcept },  // OPTIONAL  Description of identifier
4  "system" : "<uri>", // The namespace for the identifier value
5  "value" : "$lt;string>", // The value that is unique
6  "period" : { Period }, // OPTIONAL Time period when id is/was valid for use
7  "assigner" : { Reference(Organization) }  // OPTIONAL  Organization that issued id (may be just text)
8}

CodeableConcept

1{
2  // from Element: extension
3  "coding" : [{ Coding }], // Code defined by a terminology system
4  "text" : "<string>" // Plain text representation of the concept
5}

Coding

1{ 
2  "system" : "<uri>", // Identity of the terminology system
3  "version" : "<string>",  // OPTIONAL  Version of the system - if relevant
4  "code" : "<code>", // Symbol in syntax defined by the system
5  "display" : "<string>", // Representation defined by the system
6  "userSelected" : <boolean>  // OPTIONAL  If this coding was chosen directly by the user
7}

Agentforce Health Developer Guide