This page is part of the IHE Patient Demographics Query for Mobile (v3.0.0: Publication) based on FHIR (HL7® FHIR® Standard) R4. This is the current published version. For a full list of available versions, see the Directory of published versions

2:3.119 Patient Demographics Match [ITI-119]

This section corresponds to transaction [ITI-119] of the IHE Technical Framework. Transaction [ITI-119] is used by the Patient Demographics Consumer and Patient Demographics Supplier Actors that implement the Match Operation Option. The [ITI-119] transaction is used to query on patient identity information and get back resulting Patient resources.

2:3.119.1 Scope

This transaction is used by the Patient Demographics Consumer to request that the Patient Demographics Supplier identify patient records that match the demographics supplied in the request message. The request is received by the Patient Demographics Supplier. The Patient Demographics Supplier processes the request and returns a response in the form of demographics information for the matching patients.

2:3.119.2 Actors Roles

Table 2:3.119.2-1: Actor Roles

2:3.119.3 Referenced Standards

• HL7 FHIR Release 4

2:3.119.4 Messages

Figure 2:3.119.4-1: Interaction Diagram

2:3.119.4.1 Match Patient Resource Message

This message represents a request to invoke the FHIR’s operation $match on Patient. It is sent from the Patient Demographics Consumer to the Patient Demographics Supplier.

2:3.119.4.1.1 Trigger Events

When a Patient Demographics Consumer needs the Patient Demographics Supplier to identify Patient records that match a known set of data, it issues the Match Patient Resource Message.

2:3.119.4.1.2 Message Semantics

The Patient Demographics Consumer invokes the PDQm $Match Operation on the Patient Demographics Supplier. The operation is invoked by submitting an HTTP POST request to the Patient Demographics Supplier at the path:

    [base]/Patient/$match

The HTTP Body SHALL consist of a FHIR Parameters Resource conforming to the PDQm Match input Parameters Profile.

• The resource parameter SHALL be set to a Patient Resource containing the demographic information for which the Patient Demographics Consumer desires a match. The Patient Resource SHALL conform to the PDQm Patient Profile for $match Input.

• The onlyCertainMatches parameter MAY be optionally set to true to indicate that the Patient Demographics Consumer would only like matches returned when they are certain to be matches for the subject of the request. Note that there might still be multiple results returned in the response when the same person has multiple records in the Patient Demographics Supplier. FHIR-37361 and FHIR-40880 request an additional parameter for specifying that matches SHOULD only be returned when there is exactly 1 certain match. When onlyCertainMatches is set to false, then the Patient Demographics Supplier might return records representing multiple persons with each result graded accordingly.

• The count parameter can be used to limit the number of results the Patient Demographics Supplier returns. The Patient Demographics Supplier SHALL return up to count results. Note that this might cause relevant results to be omitted from the response. In cases where there are multiple records for the same person, the use of count could cause even certain matches to be omitted from the response.

When onlyCertainMatches and count are not used, the Patient Demographics Consumer MAY optionally submit the Patient Resource as the HTTP POST body without wrapping it in a Parameters Resource. Doing so is equivalent to submitting a Parameters resource containing the Patient resource in the resource parameter and no other parameters.

2:3.119.4.1.2.1 Providing Mother’s Maiden Name

When the Patient Demographics Consumer wishes to provide the Patient’s mother’s maiden name as input to patient matching, it SHALL do so by including the mothersMaidenName extension on the Patient Resource supplied as input.

2:3.119.4.1.2.1 Populating Expected Response Format

The FHIR standard provides encodings for responses as either XML or JSON. Patient Demographics Suppliers SHALL support both message encodings, whilst Patient Demographics Consumers SHALL support one and MAY support both. See ITI TF-2: Appendix Z.6 for details.

2:3.119.4.1.3 Expected Actions

The Patient Demographics Supplier SHALL return demographic records that reflect the match to the Patient Resource provided by the Patient Demographics Consumer. The Patient Demographics Supplier SHALL respond with a Match Patient Resource Response message.

The response provided by the Patient Demographics Supplier to the Patient Demographics Consumer is a list of matching patients from the Patient Demographics Supplier’s information source. The mechanics of the matching algorithms used are internal to the Patient Demographics Supplier and are outside the scope of this framework.

The Patient Demographics Supplier SHALL support at least one patient identifier domain and MAY support multiple identifier domains. Query responses MAY return patient identifiers from one or multiple patient identifier domains.

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for guidance for Access Denied.

The Patient Demographics Supplier SHALL respond to the query request as described by the following cases with a Match Patient Resource Response message, and SHALL behave according to the cases listed below:

Case 1: The Patient Demographics Consumer specified a Patient but did not specify the onlyCertainMatches or count parameters. The Patient Demographics Supplier finds exactly one patient record matching the criteria sent as a Patient Resource. Example input.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the result set. One entry is returned from the Patient Demographics Supplier for the Patient Resource found. The entry has a search.score populated with a value between 0 and 1 representing the match algorithm’s score, and the match-grade extension is supplied with the appropriate code to describe the match quality. Example output.

Case 2: The Patient Demographics Consumer specified a Patient but did not specify the onlyCertainMatches or count parameters. The Patient Demographics Supplier finds multiple (more than one) patient records matching the criteria sent as a Patient Resource. Example input.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the result set. One entry is returned from the Patient Demographics Supplier for each Patient Resource found. Each entry has a search.score populated with a value between 0 and 1 representing the match algorithm’s score, and the match-grade extension is supplied with the appropriate code to describe the match quality. The results are ordered from most likely to least likely. Example output.

Case 3: The Patient Demographics Consumer specified a Patient and onlyCertainMatches set to true. The Patient Demographics Supplier finds a patient record matching the criteria sent as a Patient Resource, and the match-grade is certain. Example input.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the result set. One entry is returned from the Patient Demographics Supplier for the Patient Resource found. The entry has a search.score populated with a value between 0 and 1 representing the match algorithm’s score, and the match-grade extension is set to certain to indicate a certain match. Example output.

Case 4: The Patient Demographics Consumer specified a Patient and onlyCertainMatches set to true. The Patient Demographics Supplier finds exactly one patient record matching the criteria sent as a Patient Resource, but the match grade is not certain. Example input.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the zero result set. No entry attributes are provided in the result.

Case 5: The Patient Demographics Consumer specified a Patient and onlyCertainMatches set to true. The Patient Demographics Supplier finds multiple (more than one) patient records matching the criteria sent as a Patient Resource, and it cannot confirm that the multiple resources correspond to the same person.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the zero result set. No entry attributes are provided in the result. Example output.

Case 6: The Patient Demographics Consumer specified a Patient and a count parameter. The Patient Demographics Supplier finds multiple (more than one) patient records matching the criteria sent as a Patient Resource. Example input.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the result set. One entry is returned from the Patient Demographics Supplier for each Patient Resource found. Each entry has a search.score populated with a value between 0 and 1 representing the match algorithm’s score, and the match-grade extension is supplied with the appropriate code to describe the match quality. The results are ordered from most likely to least likely, and results beyond count are omitted from the result set. Example output.

Case 7: The Patient Demographics Supplier fails to find in its information source, any patient record matching the criteria sent as a Patient Resource. Example input.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the zero result set. No Patient Resources are provided in the result. The Patient Demographics supplier MAY return one or more OperationOutcome Resources providing more details on the outcome of the operation, but any OperationOutcome Resources returned do not have error or fatal severity. Example output.

Case 8: The Patient Demographics Supplier finds a deprecated Patient record that matches the query parameters. In this case, it SHALL return HTTP 200 (OK), and a Resource Bundle with one of the following properties:

• The returned Resource Bundle contains the Patient, which has the active element set to false.

• The returned Resource Bundle does not include the deprecated Patient record. It MAY contain other records that match the search, or it MAY be empty.

The option chosen by the Patient Demographics Supplier is based on policy.

Case 9: One or more issues were encountered during the request.

An appropriate HTTP failure code is returned as the status code by following the expectations of a FHIR Operation Response.

Either a single OperationOutcome or a Resource Bundle of OperationOutcome Resources is returned describing the nature of the issue. Example OperationOutcome, Example Bundle.

Case 10: The Patient Demographics Supplier finds a patient record matching the criteria sent as a Patient Resource, but some warnings are produced during the operation.

HTTP 200 (OK) is returned as the HTTP status code.

A Resource Bundle is returned representing the result set. One entry is returned from the Patient Demographics Supplier for the Patient Resource found. The entry has a search.score populated with a value between 0 and 1 representing the match algorithm’s score, and the match-grade extension is supplied with the appropriate code to describe the match quality. In addition, one or more OperationOutcome resources are returned to describe the warnings. Example output. OperationOutcome Resources returned do not have error or fatal severity. Example output.

2:3.119.4.2 Match Patient Resource Response Message

2:3.119.4.2.1 Trigger Events

The Patient Demographics Supplier has results or errors to report to the Patient Demographics Consumer. This MAY include finding zero or more patient demographics matching the input parameters specified by the Patient Demographics Consumer as a result of a Match Patient Resource Request. This MAY include errors or Access Denied.

2:3.119.4.2.2 Message Semantics

The Match Patient Resource Response conforms to the PDQm Match Output Bundle Profile and is sent from the Patient Demographics Supplier to the Patient Demographics Consumer as a Bundle of Patient Resources. The content-type of the response will depend upon the requested response format indicated by the Patient Demographics Consumer.

See ITI TF-2: Appendix Z.6 for more details on response format handling. See ITI TF-2: Appendix Z.7 for guidance for Access Denied.

2:3.119.4.2.2.1 Patient Resource Definition in the Context of Match Patient Resource Response

The Patient Resource(s) contained within the Query Patient Resource Response message SHOULD conform to Patient Profile for PDQm.

2:3.119.4.2.2.2 Mother’s Maiden Name

Patient Demographics Suppliers SHALL include the mother’s maiden name, if known, in this extension: http://hl7.org/fhir/R4/extension-patient-mothersmaidenname.html.

2:3.119.4.2.2.3 Resource Bundling

Please see ITI TF-2: Appendix Z.1 for details on the IHE guidelines for implementing FHIR bundles.

2:3.119.4.2.2.4 Quality of Match

The Patient Demographics Supplier SHALL convey the quality of each match based on strength of the particular result to the supplied Patient Resource. The mechanism for determining the confidence of match is considered a product specific feature and is not specified in this transaction. When doing so, it SHALL represent the confidence of a particular match within the bundle as a score attribute. See FHIR Relevance section http://hl7.org/fhir/R4/search.html#score. In addition, the Patient Demographics Supplier SHALL include in each Patient Bundle entry the match-grade extension with the appropriate code to describe the match quality.

2:3.119.4.2.3 Expected Actions

The Patient Demographics Consumer SHALL process the response in some manner specific to its application function (for example: displaying on a user interface). This application behavior is not specified by IHE.

The constraints specified in Section 3.119.4.2.2 represent the minimum set of demographics information that MUST be implemented by a Patient Demographics Supplier. This does not prevent the Patient Demographics Supplier from sending additional FHIR attributes in a response; such as extensions, text, etc. The Patient Demographics Consumer SHALL ignore additional attributes and extensions if not understood.

2:3.119.5 Security Considerations

See the general Security Consideration in ITI TF-1: 38.5.

2:3.119.5.1 Security Audit Considerations

The Patient Demographics Match Transaction is a Query Information event as defined in Table 3.20.4.1.1.1-1. The actors involved SHALL record audit events according to the following:

2:3.119.5.1.1 Patient Demographics Consumer Audit

The Patient Demographics Consumer when grouped with ATNA Secure Node or Secure Application Actor SHALL be able to record an audit event consistent with the Patient Demographics Consumer AuditEvent. Audit Example for a PDQm Match transaction from consumer perspective.

2:3.119.5.1.2 Patient Demographics Supplier Audit

The Patient Demographics Supplier when grouped with ATNA Secure Node or Secure Application Actor SHALL be able to record an audit consistent with the Patient Demographics Supplier AuditEvent. Audit Example for a PDQm Match transaction from supplier perspective.

2:3.119.5.2 Use with the Internet User Authorization (IUA) Profile

The Internet User Authorization (IUA) Profile provides support for user authentication, app authentication, and authorization decisions. When PDQm actors are grouped with IUA actors there are additional security and privacy functionality enabled by this grouping. There are additional requirements and functionality enabled through scope definitions that are transaction-specific.

A Patient Demographics Consumer, when grouped with an IUA Authorization Client, SHALL use Get Access Token [ITI-71] to request the following scope from the IUA Authorization Server. This enables the Patient Demographics Consumer to get corresponding identifiers with the Patient Demographics Match [ITI-119] transaction with the authorizing token in the combined transaction Incorporate Access Token [ITI-72].

The Patient Demographics Supplier, when grouped with an IUA Resource Server, SHALL require Incorporate Access Token [ITI-72] in all Patient Demographics Match [ITI-119] transactions, SHALL enforce the authorization decision in the token, and MAY further enforce policies beyond those made by the Authorization Server such as consent or business rules.

scope: ITI-119

This scope request authorizes the full [ITI-119] transaction. This scope implicitly requests patient-specific queries for getting corresponding demographics. Further scope refinement is allowed in realm or project-specific situations; these scopes would be in addition to the scope defined here.