Search criteria for appointment slots in Epic FHIR

Question

I'm using Epic's FHIR API (with Argonaut) to search for available appointments, in their private sandbox:

POST /api/FHIR/STU3/Appointment/$find

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "startTime",
            "valueDateTime": "2022-03-22T08:15:00Z"
        },
        {
            "name": "endTime",
            "valueDateTime": "2022-04-02T08:15:00Z"
        }
    ]
}

And this gives me some temporary appointments starting at the desired date and time. No problem. However, if I add service-type as a parameter in the body:

POST /api/FHIR/STU3/Appointment/$find

{
    "resourceType": "Parameters", 
    "parameter": [
        {
            "name": "startTime", 
            "valueDateTime": "2022-03-23T15:30:00Z"
        }, 
        {
            "name": "endTime", 
            "valueDateTime": "2022-04-02T15:30:00Z"
        },
        {
            "name": "service-type",
            "valueCodeableConcept": {
                "coding": [
                    {
                        "system": "urn:oid:1.2.840.114350.1.13.861.1.7.3.808267.11",
                        "code": "40111223"
                    }
                ]
            }
        }
    ]
}

I get a slightly different response. I see temporary appointments with the same slot IDs (different appointment IDs of course), but also see an OperationOutcome at the end of the Bundle:

      {
            "fullUrl": "urn:uuid:00000000-0007-792f-cd9b-f1f44af2c17c",
            "resource": {
                "resourceType": "OperationOutcome",
                "issue": [
                    {
                        "severity": "information",
                        "code": "value",
                        "details": {
                            "coding": [
                                {
                                    "system": "urn:oid:1.2.840.114350.1.13.0.1.7.2.657369",
                                    "code": "59109",
                                    "display": "An element value is invalid."
                                }
                            ],
                            "text": "An element value is invalid."
                        },
                        "diagnostics": "1.2.840.114350.1.13.861.1.7.3.808267.11",
                        "location": [
                            "/f:service-type(oid)"
                        ],
                        "expression": [
                            "service-type (oid)"
                        ]
                    }
                ]
            },
            "search": {
                "mode": "outcome"
            }
        }

The service-type system and code I used here were taken right from the example on Epic's page on the $find API. I see similar results when I use service-types from actual Slots in the Epic sandbox. And if I put in a location-reference, it seems to be ignored and appointments at other locations are sometimes returned. The net result of all this is that it seems only the start and end time are honored when finding appointments.

How can I narrow down the results of a $find call using criteria other than the start and end date?

Answer 1

The source of truth for this API should be the fhir.epic.com documentation, but since this is a common question, I'll post some information here:

1. $find is not a good option for patient open scheduling. I don't know if that is your use case or not, but it is a common question, so I'll address it anyway.
2. $find invokes a rules engine that is defined by each healthcare organization. The logic of that rules engine is 100% up to the healthcare organization to define. In order for $find to work for you, you'll need very specific pre-coordination to build the logic in that engine.
3. The Epic sandboxes only have a very basic rules engine built out. It isn't particularly "real-world"-y. And it is probably good that it isn't, as it serves as an early warning that this API may not be the API you are looking for.

The $find API is a way to support cross-organization scheduling. For example, if you want front desk staff to be able to schedule a follow up visit at another organization across town that they have an established business relationship. For example, if a PCP office wants to schedule a dermatology visit for you at an external org. Note that the user in this case is the organization's scheduling staff, not the patient.

Specifically, Epic's $find support is based on Use Case 1 and 2 in the Argonaut Implementation Guide.