Searching


Searching for resources is fundamental to the mechanics of FHIR. The following sections describe how the Veradigm FHIR API supports specific search functions from a general perspective. Each FHIR resource supports its own unique set of parameters. Those parameters are included in the Resource-specific documentation.


For information on searching, see Search - FHIR v4.0.1 (hl7.org).

Date Searches

Date searches can use the following formats: YYYY, YYYY-MM, or YYYY-MM-DD. (You cannot search for a month without a year.) If the date element is a date-time, you can also add the time. An hour and a minute value are required, but a seconds value is optional. Include a time zone. The full data parameter format is:

yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]

FHIR supports a series of comparison operators for date range searches. However, comparison operators are optional. Not using a comparison operator limits the search results to exact matches. When searching by dates, the following comparison operators are used instead of symbols:

  • eq: equal. For example: /medicationrequest?date=eq2022-01-01. Means: "Get me the medication requests for the date January 1, 2022."
  • gt: greater than. For example: /medicationrequest?date=gt2022-01-01. Means: "Get me the medication requests for dates after January 1, 2022."
  • ge: greater than or equal to.
  • lt: less than.
  • le: less than or equal to.

These comparison operators can be combined to search by a date range. For example:

/medicationrequest?date=ge2022-01-01&date=le2022-1-31 Means: "Get me the medication requests for the month of January 2022."

Common Search Parameters

The Veradigm FHIR API currently supports the following common search parameters:

  • _id: Search by the resource ID. For example: GET [FHIR path]/Patient?_id=INF-101. Means: "Get the patient resource with the _ID equal to INF-101."
  • _lastUpdated: Search by the resource’s last updated date. For example: GET [FHIR path]/Observation?_lastUpdated=ge2022-03-01. Means: "Get the observations that have changed since March 1, 2022."
  • _count: Do not return more than this number of resources in each response. For example: GET [FHIR path]/Observation?_lastUpdated=ge2022-03-01&_count=1. Means: "Get the observations that have changed since March 1, 2022, but include only one resource in each response."
  • _include: Include the subject resources in the results. This parameter works only in conjunction with the Provenance resource at this time. Use _include to get the Medication resource referenced from the MedicationRequest resource. See the section below.

    When returning paged results for a search with _include resources, all _include resources that are related to the primary resources returned for the page should also be returned as part of that same page, even if some of those resource instances have previously been returned on previous pages. This allows both sender and receiver to avoid caching results of other pages.

  • _revinclude: Include any resources that refer to the primary resource in the result. This parameter works only in conjunction with the Provenance resource at this time. See the section below.
  • _summary: Return only a subset of the resource information.

For more information on how to work with these parameters, go to: Search - FHIR v4.0.1 (hl7.org).

Provenance

The Provenance resource tracks information about the activity that created, revised, deleted, or signed a version of a resource. This information can be used to form assessments about its quality, reliability, trustworthiness, or to provide pointers for where to go to further investigate the origins of the resource and the information in it. The Veradigm FHIR API does not currently support searching on the Provenance resource. If you have the resource _ID value, you can perform a GET, but you cannot search.

Searching with Provenance

The Veradigm FHIR API supports searching by provenance with the _include and _revinclude parameters. Use the _include parameter to get resources that are referenced by the primary resource. For example:

[FHIR path]/allergyintolerance?_id=INF-101&_revinclude=Provenance:target Means: "Get me the AllergyIntolerance resource with the _ID INF-101 and include all provenance records that this AllergyIntolerance targets."


For more information on the Provenance resource, see Provenance - FHIR v4.0.1 (hl7.org).

Error Handling in Searches

The Veradigm FHIR API returns the following errors when a successful 200 message is not returned:

  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not found
  • 413: Request too large

Redacted Data in Searches

Under some circumstances, the Veradigm FHIR API may return data marked as “redacted.” This occurs when the Veradigm Clinical Authorization Service determines that the person requesting the data is not authorized to view it. However, knowing that there is data available may be relevant to the user's workflow. This is intended to prevent patient safety issues.