Patient Demographics Query for mobile (PDQm)
2.4.0 - Trial-Implementation International flag

This page is part of the IHE Patient Demographics Query for Mobile (v2.4.0: Trial Implementation) based on FHIR R4. This is the current published version. For a full list of available versions, see the Directory of published versions

2:3.78 Mobile Patient Demographics Query [ITI-78]

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

2:3.78.1 Scope

This transaction is used by the Patient Demographics Consumer to solicit information about patients whose demographics data match data provided in the search parameters on 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.78.2 Actors Roles

Table 2:3.78.2-1: Actor Roles

Actor Role
Patient Demographics Consumer Requests a list of patients matching the supplied set of demographics criteria (example: ID or Name) from the Patient Demographics Supplier. The Patient Demographics Consumer populates its attributes with demographic information received from the Patient Demographics Supplier.
Patient Demographics Supplier Returns demographic information for all patients matching the demographics criteria provided by the Patient Demographics Consumer

2:3.78.3 Referenced Standards

2:3.78.4 Messages

Patient DemographicsConsumerPatient DemographicsSupplierQueryQuery Patient ResourceQuery Patient Resource ResponseRetrieveRetrieve Patient ResourceRetrieve Patient Resource Response


Figure: 2:3.78.4-1: Interaction Diagram

2:3.78.4.1 Query Patient Resource message

This message represents a parameterized search from the Patient Demographics Consumer to the Patient Demographics Supplier.

2:3.78.4.1.1 Trigger Events

When a Patient Demographics Consumer needs to select a patient based on demographic information about patients whose information matches a minimal set of known data, it issues a Query Patient Resource.

2:3.78.4.1.2 Message Semantics

The Patient Demographics Consumer may use GET or POST based searches. The Patient Demographics Supplier shall support both GET and POST based searches. The search target follows the FHIR http specification, addressing the Patient Resource type http://hl7.org/fhir/R4/http.html:

    [base]/Patient?<parameters>

This URL is configurable by the Patient Demographics Supplier and is subject to the following constraints. The <parameters> represents a series of encoded name-value pairs representing the filter for the search parameters specified below, as well as control parameters to modify the behavior of the Patient Demographics Supplier such as response format, or pagination.

2:3.78.4.1.2.1 Search Parameters

The Patient Demographics Consumer may supply, and the Patient Demographics Supplier shall be capable of processing, all parameters listed below. All parameter values shall be appropriately encoded per RFC3986 “percent” encoding rules. Note that percent encoding does restrict the character set to a subset of ASCII characters which is used for encoding all other characters used in the URL. Patient Demographics Suppliers may choose to support additional parameters beyond the subset listed below. Any additional parameters supported shall be supported according to the core FHIR specification. Such additional parameters are considered out of scope for this transaction. Any additional parameters not supported should be ignored, See http://hl7.org/fhir/R4/search.html#errors.

FHIR defines methods of supporting multiple parameter values in an AND and OR relationship. The Patient Demographics Supplier shall support both AND and OR relationships. See FHIR specification on Composite Search Parameters http://hl7.org/fhir/R4/search.html#combining.

Parameter definitions
_id This parameter of type string, when supplied, represents the resource identifier for the Patient Resource being queried. See ITI TF-2: Appendix Z.2.3 for use of the string data type. Note: A search using _id is always an exact match search.
active This parameter of type token, when supplied, specifies the active state. The active state indicates whether the patient record is active. Note: use active=true
family and given These parameters of type string, when supplied, specify the name of the person whose information is being queried. For this parameter the Patient Demographics Consumer may use either family name, given name or a combination of both names to filter by family, given or family and given names respectively. See ITI TF-2: Appendix Z.2.3 for use of the string data type.
identifier This repeating parameter of type token, when supplied, specifies an identifier associated with the patient whose information is being queried (e.g., a local identifier, account identifier, etc.). See ITI TF-2: Appendix Z.2.2 for use of the token data type. If multiple instances of this parameter are provided in the query, the query represents a logical AND condition (i.e., all of the associated identifiers must match). For example, a query searching for patients having identifier145 assigned by authority “1.2.3.4” and SSN 123456789 would be represented as:
?identifier=urn:oid:1.2.3.4|145&identifier=urn:oid:2.16.840.1.113883.4.1|123456789
If no system portion of the identifier parameter is specified, then the matching would be performed on any identifier regardless of issuing system.
telecom This parameter of type token, when supplied, specifies the telecommunications details
birthdate This parameter of type date, when supplied, specifies the birth date of the person whose information is being queried. The Patient Demographics Consumer shall use the date and interval mechanism to indicate a specific date of birth or a date that lies within the range specified by the parameter. See http://hl7.org/fhir/R4/search.html#date
address This parameter of type string, when supplied, specifies one or more address parts associated with the person whose information is being queried. For details on matching rules, see ITI TF-2: Appendix Z.2.3.
address-city,
address-country,
address-postalcode,
address-state
These parameters of type string, when supplied, specify a match against the specified address part associated with the person whose information is being queried. Note that national conventions for addresses may affect utility of these fields.
gender This parameter of type token, when supplied, specifies the administrative gender of the person whose information is being queried. For this parameter item, a single administrative gender code from value set http://hl7.org/fhir/R4/valueset-administrative-gender.html shall be specified as the only value of the token. See ITI TF-2: Appendix Z.2.2 for use of the token data type.
mothersMaidenName This parameter of type string, when supplied, specifies the mother’s maiden (unmarried) name, commonly collected to help verify patient identity. This is search extension defined in FHIR
Expression: Patient.extension(http://hl7.org/fhir/StructureDefinition/patient-extensions-Patient-mothersMaidenName)

For example

GET https://server.example.com/fhir/Patient?family=MOHR&given=ALICE&active=true&gender=female
Accept: application/fhir+json; fhirVersion=4.0
2:3.78.4.1.2.2 Parameter Modifiers

Patient Demographics Suppliers shall support the “:exact” parameter modifier on all search parameters of type string. When supplied by the Patient Demographics Consumer, the “:exact” parameter modifier instructs the Patient Demographics Supplier that exact matching should be performed. The Patient Demographics Consumer should not use, and Patient Demographics Supplier may ignore, any additional parameter modifiers listed in the FHIR standard, which are considered out of scope in the context of this transaction

2:3.78.4.1.2.3 Populating Which Domains are Returned

The Patient Demographics Consumer may constrain the domains from which patient identifiers are returned from the Patient Demographics Supplier in the resulting bundle. The Patient Demographics Consumer shall convey this by specifying the patient identity domains in the system component of repeating identifier parameters using the OR format (example of using , in a request for identifier domain 1.2.3 OR 4.5.6):

&identifier=urn:oid:1.2.3|,urn:oid:4.5.6|

For example, a Patient Demographics Consumer wishing to filter for patients with a last name of SMITH having identifiers from an identity domain with OID 1.2.3.4.5 would convey this search using the AND format as (example of requesting a family name of SMITH AND in the identifier domain 1.2.3.4.5):

  ?family=SMITH&identifier=urn:oid:1.2.3.4.5|

The Patient Demographics Consumer shall populate the patient identity domain portion of the token with values described in ITI TF-2: Appendix E.

2:3.78.4.1.2.4 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.78.4.1.3 Expected Actions

The Patient Demographics Supplier shall return demographic records that reflect the match to all of the search criteria provided by the Patient Demographics Consumer. The Patient Demographics Supplier shall respond with a Query Patient Resource Response message synchronously (i.e., on the same connection as was used to initiate the request).

The Patient Demographics Supplier shall return all exact matches to the search parameters sent by the Patient Demographics Consumer; IHE does not further specify matching requirements. The Patient Demographics Supplier may be able to perform other string matching (e.g., case insensitive, partial matches, etc.) which shall be indicated in its CapabilityStatement Resource (see ITI TF-2: Appendix Z.4).

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. Section 3.78.4.1.2.4 describes how the Patient Demographics Consumer may filter results based on identifiers from one or more patient 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 Query Patient Resource Response message, and shall behave according to the cases listed below:

Case 1: The Patient Demographics Supplier finds at least one patient record matching the criteria sent as HTTP search parameters. No patient identifier domains are requested via the mechanism specified as specified in Section 3.78.4.1.2.4.

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

A Resource Bundle is returned representing the result set. The Patient Demographics Supplier populates the total property of the bundle with the total number of matching results. One entry is returned from the Patient Demographics Supplier for each Patient Resource found.

Case 2: The Patient Demographics Supplier finds at least one patient record matching the criteria sent in the search parameters. One or more patient identifier domains are requested via the mechanism specified in Section 3.78.4.1.2.4, and Patient Demographics Supplier recognizes all domains.

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

The Patient Demographics Supplier performs its matching and returns a bundle as described in Case 1. The Patient Demographics Supplier eliminates identifiers from the result set which do not exist in the list specified per Section 3.78.4.1.2.4 (domains to be returned).

Case 3: The Patient Demographics Supplier fails to find in its information source, any patient record matching the criteria sent as HTTP search parameters.

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

A Resource Bundle is returned representing the zero result set. The Patient Demographics Supplier populates the total with a value of 0 indicating no results were found. No entry attributes are provided in the result.

Case 4: The Patient Demographics Supplier is not an authority for one or more of the domains specified per Section 3.78.4.1.2.4.

There are two acceptable responses. The preferred response is a HTTP 404 to indicate that the domain is not recognized, but it is acceptable to respond with a HTTP 200 with the results available (0..*).

An OperationOutcome Resource is returned indicating that the patient identity domain is not recognized in an issue having:

Attribute Value
severity warning
code not-found
diagnostics “targetSystem not found”

The OperationOutcome Resource may indicate the search parameter used and the domain in error within the diagnostics attribute. See FHIR discussion of search error handling http://hl7.org/fhir/R4/search.html#errors

Case 5: The Patient Demographics Supplier is not capable of producing a response in the requested format specified by _format parameter (specified in Section 3.78.4.1.2.5).

HTTP 406 (Not Acceptable) is returned as the HTTP status code.

An OperationOutcome Resource is returned indicating that the requested response format is not supported in an issue having:

Attribute Value
severity error
code not-supported

The Patient Demographics Supplier may be capable of servicing requests for response formats not listed in Section 3.78.4.1.2.5, but shall, at minimum, be capable of producing XML and JSON encodings.

The Patient Demographics Supplier may return other HTTP status codes to represent specific error conditions. When HTTP error status codes are returned by the Patient Demographics Supplier, they shall conform to the HTTP standard RFC2616. Their use is not further constrained or specified by this transaction.

2:3.78.4.2 Query Patient Resource Response message

2:3.78.4.2.1 Trigger Events

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

2:3.78.4.2.2 Message Semantics

The Query Patient Resource Response 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.78.4.2.2.1 Patient Resource Definition in the Context of Query Patient Resource Response

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

2:3.78.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.78.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.78.4.2.2.4 Incremental Response Processing - Paging of Resource Bundle

The Patient Demographics Supplier shall represent these incremental responses as specified in FHIR Paging

2:3.78.4.2.2.5 Quality of Match

The Patient Demographics Supplier may convey the quality of each match based on strength of the particular result to the supplied search parameters. The mechanism for determining the confidence of match is considered a product specific feature and is not specified in this transaction.

If the Patient Demographics Supplier wishes to convey the quality of match, 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

2:3.78.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.78.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.

The Patient Demographics Consumer should be robust as the response may contain Patient Resources that match the search parameters but are not compliant with the PDQm constraints defined in Patient Profile for PDQm.

The Patient Demographics Consumer should follow the Safety Guidelines for Client Search

2:3.78.4.3 Retrieve Patient Resource message

This message represents an HTTP GET from the Patient Demographics Consumer to the Patient Demographics Supplier and provides a mechanism for retrieving a single Patient Resource with a known resource identifier.

2:3.78.4.3.1 Trigger Events

When the Patient Demographics Consumer possesses a Patient Resource’s identifier (either through query, database lookup, or other mechanism) for which it requires additional or new information, it issues a Retrieve Patient Resource interaction.

2:3.78.4.3.2 Message Semantics

The Retrieve Patient Resource is conducted by executing an HTTP GET against the Patient Demographics Supplier’s Patient Resource URL, providing the resource id of the patient being retrieved. The target is formatted as:

GET [base]/Patient/[resourceId]

The Patient Demographics Supplier shall respond to this query by sending a single Patient Resource instance. The specification for [base] is identified in Section 3.78.4.1.2.

The resourceId included in the request always represents the unique identifier for the Resource within the scope of the URL. For example, while http://example1.org/ihe/Patient/1 and http://example2.com/ihe/Patient/1 both contain the same [resourceId], they reference two different resource instances.

Note: The use of “http” or “https” in URL does not override requirements to use TLS for security purposes.

2:3.78.4.3.3 Expected Actions

The Patient Demographics Supplier shall retrieve the demographic record indicated by the Resource identifier on the HTTP GET supplied by the Patient Demographics Consumer. The Patient Demographics Supplier shall respond to the retrieve request as described by the following cases:

Case 1: The Patient Demographics Supplier finds the patient demographics record matching the resourceId sent in the HTTP request.

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

A Patient Resource is returned representing the result.

Case 2: The Patient Demographics Supplier fails to find the patient demographics record matching the resourceId sent in the HTTP request.

HTTP 404 (Not Found) is returned as the HTTP status code

An OperationOutcome Resource is returned indicating that the Patient Resource could not be found, in an issue having:

Attribute Value
severity error
code not-found

The Patient Demographics Supplier may return other HTTP status codes to represent specific error conditions. When HTTP error status codes are returned by the Patient Demographics Supplier, they shall conform to the HTTP standard RFC2616. Their use is not further constrained or specified by this transaction.

2:3.78.4.4 Retrieve Patient Resource Response message

The Patient Demographics Supplier’s response to a successful Retrieve Patient Resource message shall be an HTTP 200 (OK) Status code with a Patient Resource, or an appropriate error code.

2:3.78.4.4.1 Trigger Events

The Patient Demographics Supplier found patient demographic record matching the Resource identifier specified by the Patient Demographics Consumer.

2:3.78.4.4.2 Message Semantics

The Retrieve Patient Resource response is sent from the Patient Demographics Supplier to the Patient Demographics Consumer as a single Patient Resource.

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.

If the Patient Demographics Supplier is unable to produce a response in the requested format, it shall respond with an HTTP 400 error indicating that it was unable to fulfill the request. The Patient Demographics Supplier may be capable of servicing requests for response formats not listed, but shall, at minimum, be capable of producing XML and JSON encodings.

2:3.78.4.4.2.1 Patient Resource Definition in the Context of Retrieve Patient Resource Response

The Patient Resource definition in the context of a retrieve interaction is the FHIR definition of the Patient Resource, see http://hl7.org/fhir/R4/patient.html.

2:3.78.5 Security Considerations

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

2:3.78.5.1 Security Audit Considerations

The Mobile Patient Demographics Query 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.78.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 a Patient Demographics Consumer AuditEvent. Audit Example for a PDQm Query transaction from consumer perspective.

2:3.78.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 a Patient Demographics Supplier AuditEvent. Audit Example for a PDQm Query transaction from supplier perspective.

2:3.78.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 Mobile Patient Demographics Query [ITI-78] 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 Mobile Patient Demographics Query [ITI-78] 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-78

This scope request authorizes the full [ITI-78] 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.