Specialty Medication Enrollment
2.0.0 - STU2 US United States of America flag

This page is part of the Specialty Medication Enrollment (v2.0.0: STU2) based on FHIR R4. This is the current published version. For a full list of available versions, see the Directory of published versions

Search Conventions

US Core Search Guidance

Data Source and Data Consumer systems SHALL follow US Core search requirements and guidance when performing searches associated with this guide.

Required Searches

To ensure that the most common data requests are supported by all participants, Data Sources SHALL be able to return information in response to searches on the resources below–whether responding to RESTful search requests or the Specialty Rx Query message.

Notes:

  • Examples in the tables below reflect searches submitted using REST GET and POST interactions. However, when specifying searches in the Specialty Rx Query message, the URL base and patient parameter are omitted (see below)
  • Submitting searches using HTTP GET and POST is described here in the FHIR specification

Resource Parameters Example
AllergyIntolerance Per US Core 
GET [base]/AllergyIntolerance?patient=123&clinical-status=active
or
POST [base]/AllergyIntolerance/_search
Content-Type: application/x-www-form-urlencoded:
patient=123&clinical-status=active
Returns all active patient allergies and intolerances
Condition Per US Core 
GET [base]/Condition?patient=123
or
POST [base]/Condition/_search
Content-Type: application/x-www-form-urlencoded: 
patient=123
Returns all patient conditions
Observation Per US Core 
GET [base]/Observation?patient=123&category=vital-signs&date=ge2020-01-01
or
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded: 
patient=123&category=vital-signs&date=ge2020-01-01
Returns all patient vital signs recorded in the specified date period
Coverage SHALL: patient
SHOULD: beneficiary
(Not profiled in US Core)		 
GET [base]/Coverage?patient=123
or
POST [base]/Coverage/_search
Content-Type: application/x-www-form-urlencoded: 
patient=123
Returns all patient insurance coverages
MedicationRequest Per US Core 
GET [base]/MedicationRequest?patient=123&intent=order&status=active&_include=MedicationRequest:Medication
or
POST [base]/MedicationRequest/_search
Content-Type: application/x-www-form-urlencoded: 
patient=123&intent=order&status=active&_include=MedicationRequest:Medication
Returns all active patient MedicationRequest orders and the associated Medications

In addition to the required searches above, implementers SHOULD support DocumentReference searches and retrieval, to enable those participating in the fulfillment of specialty medication prescriptions to access patient information recorded in patient documents.

Resource Parameters Example
DocumentReference See US Core 
GET [base]/DocumentReference?patient=123 &category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
or
POST [base]/DocumentReference/_search
Content-Type: application/x-www-form-urlencoded: 
patient=123&category=http://hl7.org/fhir/us/core/CodeSystem/us-core-documentreference-category|clinical-note
Returns all patient clinical notes

Optional Searches

Data Consumers MAY include searches other than those outlined above.

  • Data Source systems SHALL return a search-result for each–even if the search is not supported–which SHALL include an OperationOutcome indicating when the Data Source does not support the submitted search or search parameter.

Data Sources SHALL be capable of supporting the _revinclude=Provenance:target parameter as defined in US Core, returning US Core Provenance resource(s) that reference returned resources, as specified here in US Core. In addition, Data Sources SHALL support mandatory _include parameters defined in US Core.

Each related resource SHALL be included as an entry in the response’s searchset bundle with a search.mode value of include. Below are examples:

Further search guidance

This guide leverages search guidance given in the US Core FHIR Implementation Guide and the base FHIR specification.

Search conventions in the Specialty Rx Query Message

The Specialty Rx Query message requests specific information from a given patient’s records in the responding system. The desired information is specified as FHIR search statements which are sent as parameters in the message. Responders are expected to execute these searches for the patient supplied in the request and return the results in a Specialty Rx Query Response message.

Specifying a query string

Specialty Rx messaging enables Data Consumer systems to submit requests without performing a patient match ahead of time. This accommodates a common situation where the Data Consumer hasn’t participated in previous FHIR exchanges about this patient with the Data Source and doesn’t possess the Data Source’s Patient resource ID. This also addresses challenges that may arise if the Data Consumer interacts with the Data Source via an intermediary–for example if the Data Consumer lacks details about the Data Source’s endpoint or is otherwise unable to submit patient match requests directly to the Data Source.

To support this scenario, the Specialty Rx Query message omits the patient parameter from submitted search strings, with the expectation that the Data Source will append it after locating the desired patient in its system.

For example, a search for a given patient’s vital signs that would ordinarily be stated as:

Observation?patient=[patient id]&category=vital-signs

… is submitted in the Specialty Rx Query without the patient search parameter:

Observation?category=vital-signs

Identifying the desired patient

The Data Consumer identifies the desired patient by including one or both the following in the Specialty Rx Query message:

  • a Patient resource representing the patient in the Data Consumer system (mandatory)
  • a Patient resource from the Data Source system (if available)

The Data Source locates the desired patient and completes the query string as follows, based on the submitted patient information:

  • If the request includes only the Data Consumer’s Patient, the Data Source performs a matching process and locates the associated patient in its own system. It appends its Patient ID to each submitted search string.
  • If the request includes both the Data Consumer’s Patient and Data Source’s Patient, the Data Source confirms the match and then appends its Patient ID to each submitted search string.

Returning the executed search string in the response message

In the Specialty Rx Query Response, the Data Source returns the full search string that was ultimately executed–including patient parameter–in the .link element of each returned searchset Bundle.

Bundle
    .link
        .relation = "self"
        .url = "MedicationRequest?patient=12345&status=active"
    .entry

Patient references within search results

All searches performed within a request/response exchange flow relate to a single patient, who is represented in the responder-patient parameter in the Query Response message bundle. Patient references contained in resources in searchset bundles SHOULD be resolvable to the responder-patient entry in the outer, Query Response message bundle.