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.
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:
Patient Enterprise Client Identifier (ECID); which is the unique ID of a patient in the PCR
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.
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.
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:
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.
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. |
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:
Patient Search Response profile (pcr-patient-response)
PCR Operation Outcome Profile (pcr-operationoutcome)
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.
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.
Powered by SIMPLIFIER.NET