Profiles & Operations > Search Encounter
Operation: Search Encounter
Search Encounter
The Search Encounter operation issues a parameterized query that results in a searchset Bundle that contains all the encounters related to a patient. This operation requires a patient identifier and also supports optional input parameters:
| Query Search Parameters | Description | Usage Note |
|---|---|---|
| patient.identifier (Encounter.patient.identifier) | This parameter specifies an identifier associated with the patient who is the subject of this encounter. This use of patient.identifier follows the FHIR Chaining Parameters search methodology. | the identifier of patient, which can be Ontario HCN, MRN, or ECID (Enterprise Client ID) |
| patient.gender (bundle.composition.patient.gender) | This parameter specifies the gender of the patient associated to the document. | Value may be "male", "female", "other", "unknown" |
| patient.birthDate (bundle.composition.patient.birthDate) | This parameter specifies the date of birth of the patient associated to the document. | |
| date | A date within the period the Encounter lasted | |
| class | Classification of patient encounter |
Scope
This transaction involves a request by PoS system for a set of encounters matching the specified search criteria. The request is received by the acCDR FHIR server which returns a Bundle containing the matching Encounters.
For example, a physician who has access to acCDR is seeing a new patient and wants to see a list of Encounters for that patient. The physician uses the patient information held in the system to query acCDR FHIR server for any Encounter associated with that patient. The server returns a Bundle of any matching Encounters which is then displayed to the physician as a list. The PoS system is responsibile for listing the available Encounters for the user to review;
Interaction Diagram
Actor: PoS System
Role: Requests a set of acCDR Encounters from acCDR FHIR server based on specified search criteria.
Actor: acCDR FHIR server
Role: Returns a Bundle containing Encounter instances that match the search criteria specified by the PoS system.
Specification
This operation is based on FHIR R4 search operation.
Search Encounter Operation
Search Encounter operation is based on RESTful HTTP search operation on the Encounter endpoint. acCDR FHIR server supports both GET and POST. We prefer the use of POST to avoid putting PHI in request URLs.
GET [base]/Encounter?[parameters]
POST [base]/Encounter/_search
For POST request, request parameters SHALL be specified as a string in the HTTP body. The format is parameter1=value1¶meter2=value2
This operation supports _summary parameter to return only the summary fields in the search results. The summary fields are as follows:
| Field | FHIR Path | acCDR v2 Element |
|---|---|---|
| Visit/Encounter ID | Encounter.identifier | PV1-19 |
| Type | Encounter.class | PV1-2 |
| Organization | Encounter.location where physicalType = "site" | PV1-3.4.2 |
| Service | Encounter.serviceType | PV1-10 |
| Admit Date/Time | Encounter.period.start | PV1-44 |
| Discharge Date/Time | Encounter.period.end | PV1-45 |
| Attending Provider | Encounter.participant where type = "ATND" | PV1-7 |
| Reason for Visit | Encounter.diagnosis | DG1-3 |
Query Response
If the query is valid and at least one Encounter is found, acCDR FHIR server will return a searchset bundle containing a matching Encounter resource. If no matching Encounter exists, acCDR FHIR server will return a empty bundle. The encounters in the searchset bundle will conform to the encounter profile defined in this implementation guide.
Examples
- Search Encounter by patient identifier (HCN or MRN)
GET [base]/Encounter?patient.identifier=[system]|1234567890
- Search Encounter using the combination of patient, date and location TBD
Search Encounter Response Example
Expected Behavior
See Response Handling page for additional response handling behaviour.
| Legend |
|---|
| code = OperationOutcome.issue.code |
| severity = OperationOutcome.issue.severity |
| details.coding.code=OperationOutcome.issue.details.coding.code |
| details.coding.display=OperationOutcome.issue.details.coding.display |
| details.text = OperationOutcome.issue.details.coding.text |
| HTTP Status | Scenario Description | severity | code | details.coding.code | details.coding.display | details.text |
|---|---|---|---|---|---|---|
| 200 OK | At least one encounter matching the specified search criteria is found | |||||
| 200 OK | At least one encounter matching the specified search criteria is found, but there is a consent block that prevents disclosure of patient data. Returns an OperationOutcome resource indicating that there is a consent block on the patient's record that prevents disclosure of patient data. | warning | suppressed | |||
| 200 OK | No encounters matching the specified search criteria are found. | warning | not-found | |||
| 400 Bad Request | Missing security token | error | required | Missing required security token: PIN | ||
| 400 Bad Request | Request is malformed (e.g. incorrect header value, patient identifier is missing system or value, etc) | error | -- | -- | -- | -- |
| 500 Internal Server Error | API validates the request but cannot return a valid response due to internal issues. | fatal | exception | Internal Error | ||
| 503 Service Unavailable | Indicates that the services has been temporarily taken down (on purpose) | |||||
| 504 Gateway Timeout | Downstream system(s) did not return timely response | error | timeout |