PractitionerSearch
Profiles & Operations > Practitioner Search
Practitioner Search
Practitioner search is simple RESTful interactions. It support retrieving a single Practitioner instance by Practitioner Identifiers.
Note that :Provider Person and Practitioner are used interchangeably in this document, as Practitioner is the name of the FHIR resource used to represent a Provider Person. When used in the context of FHIR, Practitioner will be used in place of Provider Person.
Scope
This transaction involves a request by the following Identifiers for:
Practitioner:
| Source | Identifier |
|---|---|
| College URI | License Number |
| Unique Provider Identifier URI | UPI |
| EPID URI | EPID |
Search needs to have a source and identifier. EPID would not be sufficient to search PPR. It needs EPID URI+EPID number.
All searches, by identifier, against PPR must be qualified with the Issuer code. Issuers are identified by the appropriate URI value. Identifiers are sequential/random numeric values issued by each source. As such, there may be overlap of identifier values across sources. This includes the Enterprise Provider Identifier (EPID) as it is a PPR assigned numeric value.
The EPID is the Enterprise” or “Entity” id for a Practitioner assigned by the PPR system. The EPID is assigned to a Provider “entity” or collection of Provider members (records from different sources for the same provider) for a single provider identity (e.g. the EPID connects Dr. Bob from UHN and Dr. Bob from Mt. Sinai as the same identity - if there is enough matching information to link the providers together).
An FHIR RESTful client sends the search by identified types of Practitioner identifiers; the request is received by the FHIR Practitioner RESTful Server which returns the requested resource. This transaction requires the use and knowledge of specific types of identifiers.
Any Practitioner Definitional Identifier may be used with this interaction; a Definitional identifier is one that is a Unique Identifier assigned by a source of information to the PPR. This type of identifier includes a Ministry of Health assigned Stakeholder number, License number issued by a Regulatory college, the EPID (Enterprise Provider ID) assigned by the Provider Registry (requires a query to PPR before using this ID), or a UPI (Unique Provider Identifier) as assigned by the former Legacy Provider Registry and ported to PPR.
In any case, the search identifier parameter must be specified along with the correct URI value assigned to the identifier issuer.
The client must provide the correct value of the identifiers as specified above, either from the Practitioner EHR record, public record or from the result of another FHIR transaction (e.g. Practitioner/Organization Match). For example, a Pharmacist may use the search operation to retrieve the Prescriber (Practitioner) information from the registry using Practitioner’s UPI from Practitioner’s EHR record, or the Practitioner’s regulatory college issued license number.
Interaction Diagrams
The following diagram illustrates the high level interaction between a FHIR Client and FHIR Provider RESTful Server. In this implementation guide, Provincial Provider Registry is playing the role of the FHIR Provider RESTful Server. All subsequent references of this actor (FHIR Provider RESTful server) should be interpreted as the Provincial Provider Registry.
The Provider FHIR transaction will use the following query and responses:
• Practitioner Search Request/Practitioner Search Response
Actor: FHIR Provider RESTful Client
Role: Requestor
Requests a detailed profile of a single practitioner based on a known Practitioner ID Issuer from the FHIR Provider RESTful Server. The FHIR Client uses the information received from the FHIR Provider RESTful Server for its own purposes. The RESTful client is referred to as the “FHIR client” in the remainder of the document.
Actor: FHIR Provider RESTful Server
Role: Information Service
Returns a bundle containing the demographic information for the single practitioner corresponding to the Issuer & ID values specified by the FHIR Provider RESTful Client. This actor is referred to as the FHIR server in the remainder of the document.
Specification
This FHIR Provider specification is based on the HL7 STU3 Search operation. It makes use of the following resources:
Note: Please note that Practitioner response is referenced in PractitionerRole response
Practitioner Search Request
The practitioner Search Request is an HTTP POST operation(Alternatively, clients can also send GET based search ) with exactly one query parameter specified below. The syntax of the request is always
POST [base]/Practitioner/_search?identifier=[system]|[value]
Or alternatively,
GET [base]/Practitioner?identifier=[system]|[value]
Note: For list of Identifiers ,see scope section above
Practitioner Search Response
General
The PPR FHIR profiles are developed to constrain value sets and cardinality of data elements in the resources listed above. Since FHIR STU3 does not support all the data elements required for this project, we have introduced a few extensions which can be found here.
Extensions
- ppr-ext-address-confidential (Address Confidential)
- ppr-ext-address-purpose (Address Purpose)
- ppr-ext-LHINCode (Local Health Integration Network)
- ppr-ext-practitioner-altname (Practitioner Alternate Name)
- ppr-ext-practitioner-deceased (Practitioner Deceased)
- ppr-ext-practitioner-restriction (Practitioner Restriction)
- ppr-ext-practitionerRole-classification (Practitioner Role Classification)
- ppr-ext-practitionerRole-status (Practitioner Role Practicing)
- ppr-ext-practitionerRole-specialty-period (Practitioner Role Specialty Period)
- ppr-ext-practitionerRole-status (Practitioner Role Status)
- ppr-ext-practitionerRole-status-effective (Practitioner Role Status Effective)
- ppr-ext-practitioner-qualification-level (Practitioner Qualification Level)
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:
| Resource | Transaction | HTTP Operations | URL | Request Body Resource | Response Body Resource |
|---|---|---|---|---|---|
| Practitioner and PractitionerRole | Search | POST | [base]/Practitioner/_search? | N/A | Bundle containing Practitioner and practitionerRole |
Alternatively, clients can also send GET based search as follows:
| Resource | Transaction | HTTP Operations | URL | Request Body Resource | Response Body Resource |
|---|---|---|---|---|---|
| Practitioner and PractitionerRole | Search | GET | [base]/Practitioner? | N/A | Bundle containing Practitioner and practitionerRole |
The interaction summary table below lists the HTTP status codes that may be returned for the search.
| Interaction | Content-Type | Body | Location | Versioning | Status Codes | Comments |
|---|---|---|---|---|---|---|
| Search (practitioner) | R | R: Bundle | N/A | N/A | 200,400,500 |
Practitioner Search Operations
The Practitioner search is invoked through a HTTP POST (alternatively GET) request specifying the issuer (e.g. URI of PPR EPID, CPSO etc.) and identifier value (EPID, UPI, etc.) of a single Practitioner instance. The response from the FHIR Provider RESTful Server will be a Practitioner Resource, or in the case of a failed search, an operation outcome resource.
Trigger Event
When a FHIR Client has the identifiers for an practitioner but does not yet have the name, contact, license and other information or wishes to retrieve an updated version of the practitioner’s information, it invokes an Practitioner search.
Expected Behaviour
The FHIR Server shall return the records that correspond to the "Issuer/identifier" combination used in the request by the FHIR Provider RESTful Client. The FHIR Server shall respond synchronously (i.e. on the same connection as was used to initiate the request).
The FHIR Server shall respond to the search request as described by the following cases and shall behave according to the use-cases listed below:
| Case | Scenario Description | Response |
|---|---|---|
| 1 | PPR finds in its information source, a provider 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 Practitioner |
| 2 | PPR cannot find a practitioner that meets the search parameter specified by the FHIR Client Application | HTTP 200 (OK) is returned as the HTTP status code. A Resource Bundle is returned representing the zero result set. |
| 3 | PPR 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. |
| 4 | PPR 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. Client should contact eHealth Ontario for trouble shooting. |
Example
Practitioner search request:
The search request can be either a GET or POST
POST [base]/Practitioner/_search?identifier=[system]|[value]
Or alternatively,
GET [base]/practitioner?identifier=[system]|[value]
Examples of a povider person search Request can be found below
POST [base]/Practitioner/_search?identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-license-physician|12324566
Or alternatively,
GET [base]/Practitioner?identifier= https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-provider-upi|3456789023
GET [base]/Practitioner?identifier=https://fhir.infoway-inforoute.ca/NamingSystem/ca-on-license-physician|12324566
Examples of a provider person search response can be found below
Example of Operation Outcome