Profiles & Operations > Patient Search

Patient Search is a simple RESTful interaction. It supports retrieving a single patient instance by patient identifier. For difference between Patient Search and Patient Read, please refer to here.

Scope

This transaction involves a request by a FHIR Client Application for the demographic and identifier information associated with a single patient record.

This transaction supports a query by two types of identifiers:

  1. Patient Enterprise Client Identifier (ECID); which is the unique ID of a patient in the PCR

  2. Patient Definitional Identifier; which can be one of either an Ontario HCN as defined under the Ministry of Health’s (MOH) Registered Persons DataBase (RPDB), a Corporate ID for a corporate model hospital, or an MRN for a standard model hospital.

In either case, the query identifier parameter must be specified with the correct URI of the identifier.

The FHIR Client Application is expected to provide the correct value of the identifiers specified above, either from the patient EHR record or from the result in another FHIR transaction. For example, an EMR can use the Patient Search operation to retrieve the patient's demographic information from the registry using the patient’s Ontario HCN from the patient’s EHR. This operation can also be used when the patient’s identifiers becomes known by other means. For example, an EMR can use the Patient EMPI Match operation to look up alternate identifiers using a patient’s demographic information. After receiving the PCR EID for the corresponding patient, the EMR uses the Patient Search operation to retrieve the patient’s demographic information from the registry.

In either case, the query identifier parameter must be specified with the correct URI of the identifier.

Storyboard

The PCR stores accurate and up-to-date patient demographics and identifiers for consistent access across the enterprise.

This storyboard demonstrates querying the PCR to get demographic information for a patient by an ECID or definitional identifier (e.g. Ontario HCN, Corporate ID.)

Narrative Example

Connor Comrade has a list of patients who need to be invited for follow up to Dr. Patricia Primary's clinic. Connor sets up a list of IDs (e.g. collected from EMR, or via the EMR querying the PCR via the PIXm or Patient EMPI Match operation) and then requests a PCR Patient Search Query through the EMR system for each ID. Connor checks the details returned in the Patient Search Query response to make sure the patients are still alive. Where a date of death or a death status has been returned, Connor makes a note to follow these up later. For all the other patients, Connor uses the details returned in the Patient Search Response messages to update the local Patient records (e.g. mailing address) in order to issue an invitation letter to each patient for the clinic.

Interaction Diagrams

The following diagram illustrates the high level interaction between a FHIR Client Application and the PCR. The Patient Search operation will use the following query and response interactions:

  • Patient Search
  • Patient Search Response

PatientSearch

Actor: FHIR Client Application

Role: Requests demographic details for a single patient based on a known identifier (e.g. ECID, Ontario HCN, or Corporate ID) from the PCR.  The FHIR Client Application may populate its local store with the demographic information received from the PCR

Actor: PCR

Role: Returns a bundle containing the demographic information for the single patient corresponding to the patient identifier specified by the FHIR Client Application.

Patient Search Operation

This operation supports an HTTP GET specifying the allowed identifiers of a single patient instance from the FHIR Client Application to retrieve that patient from the PCR.

Trigger Event

When a FHIR Client Application has the ECID (from an identifier cross-reference query or by other means) or a definitional identifier that would identify exactly one patient, it invokes a Patient Search to return exactly one patient record.

Summary of Supported Operations

The table below shows the allowed transactions for each profile and how they support FHIR endpoints, resources and their corresponding HTTP operations (https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html):

Resource Transaction HTTP Operation URL Request Body Resource Response Body Resource
Patient Search GET [base]/Patient?identifier=name|value{&_format=[mime-type]} N/A Patient

Alternatively, clients can also send POST based search as follows:

Resource Transaction HTTP Operation URL Request Body Resource Response Body Resource Notes
Patient Search POST [base]/Patient/_search{?&_format=[mime-type]} string of name value pairidentifier=[system]|[value] Patient The Content-type header field value should be "application/x-www-form-urlencoded"

The interaction summary table below lists the HTTP status codes that may be returned for the query.

Interaction Content-Type Body Location Versioning HTTP Status Codes Comments
search R R: Patient N/A N/A 200,400,404,422,500

Expected Behavior

PCR SHALL return the patient record that correspond to the ECID or the definitional identifier provided by the FHIR Client Application. PCR SHALL respond with a bundle with zero or one patient resource that contains that identifier, or an OperationOutcome resource if an internal error occurs, where applicable.

PCR SHALL respond to the query request as described by the following cases:

Case Scenario Description Response Response Example
1 PCR finds in its information source, a patient that matches the id specified by the FHIR Client Application HTTP 200 (OK) is returned as the HTTP status code. A bundle is returned that contains the Patient Search Result Bundle
2 PCR cannot find a patient that meets the search parameter specified by the FHIR Client Application HTTP 200 (OK) is returned as the HTTP status code. A Bundle Resource is returned with zero search results. The resource includes an OperationOutcome Resource with a warning indicating no patient found. The client should confirm the request criteria is valid, and if so, contact eHealth Ontario for troubleshooting. Empty Bundle Response
3 PCR detects an error in the request and could not fulfill the request HTTP 400(Bad Request) is returned as the HTTP status code. The body contains an OperationOutcome with error details, where applicable.
4 The requested resource is not supported. HTTP 404 (Not Found) is returned as the HTTP status code. The body contains an OperationOutcome with error details, where applicable.
5 Patient Search POST operation contains incorrect header value for "Content-Type" HTTP 400 (Bad Request) is returned as HTTP status code. An OperationOutcome Resource, when applicable, is returned indicating the "Content-Type" header must be set to "application/x-www-form-urlencoded". The client must fix the request and try again.
6 PCR has validated the request, but cannot return valid response (e.g. minimum of Patient ID + Name + Gender cannot be satisfied). HTTP 422 (Unprocessable Entity) is returned as the HTTP status code. An OperationOutcome Resource, when applicable, is returned indicating an issue. Client should contact eHealth Ontario for troubleshooting.
7 PCR validates the request but cannot return valid response due to internal issue. HTTP 500 (Internal Server Error) is returned as the HTTP status code. An OperationOutcome Resource is returned indicating an issue, where applicable. Client should contact eHealth Ontario for trouble shooting.

Resource Profiles

This PCR FHIR operation is based on the HL7 FHIR R4 Search operation. It makes use of the following resources:

Patient Search Request

The search request will be a GET query.

GET [base]/Patient?identifier=[system]|[value]

Or alternatively

POST [base]/Patient/_search where the requst body will be a name value pair identifier=[system]|[value]

Patient Search Response

The response from an Patient Search operation is a single patient (i.e. Patient Search Response) record (i.e. Search Response Bundle). If PCR does not found any patient based on the provided ID in Search Request, it will return an empty search result with no error, but may include an OperationOutcome with further advice.

The following resource profiles are used for Patient Search response:

The PCR FHIR profiles are developed to constrain value sets and cardinality of data elements in the resources listed above. Since FHIR does not support all the data elements required for this project, we have introduced a few extensions which are called out in the patient profile.

Examples

Search request example:

GET [base]/Patient?identifier=http://ehealthontario.ca/fhir/NamingSystem/id-registration-and-claims-branch-def-source|1234567890

Or POST based

POST [base]/Patient/_search

with HTTP body identifier=http://ehealthontario.ca/fhir/NamingSystem/id-registration-and-claims-branch-def-source|1234567890

Examples of a search response can be found here.

Patient Search Request Detail                                                                                                                                                           Back to Top

The Patient Search Request is an HTTP GET operation with following:

GET [base]/Patient?identifier=[system]|[value]

Or alteratively:

POST [base]/Patient/_search

with HTTP body identifier=[system]|[value]

There is only one search parameter allowed in this operation, which is "identifier" The identifier value can be either an ECID or definitional identifier. The identifier must contain the proper system URI value and the identifier value itself.

Example 1 (ECID):

Client invokes a search request by an ECID

ECID = 12345

GET [base]/Patient?identifier=http://ehealthontario.ca/fhir/NamingSystem/id-pcr-eid|12345

or

POST [base]/Patient/_search with HTTP body identifier=http://ehealthontario.ca/fhir/NamingSystem/id-pcr-eid|12345

If the identifier is a Definitional ID (e.g. Ontario Health Card Number definitional ID), the corresponding URI is:

http://ehealthontario.ca/fhir/NamingSystem/id-registration-and-claims-branch-def-source

And the request may look like:

GET [base]/Patient?identifier=http://ehealthontario.ca/fhir/NamingSystem/id-registration-and-claims-branch-def-source|1234567890

Or

POST [base]/Patient/_search with HTTP body identifier=http://ehealthontario.ca/fhir/NamingSystem/id-registration-and-claims-branch-def-source|1234567890

For the complete list of Definitional ID URIs, please contact the the Registries Product Team at oh-ds_registries@ontariohealth.ca.