Patient Demographics Query
Through the Founda Health Platform, Application Providers can query and retrieve patient demographics from connected Provider Organizations in a consistent way, using the IHE ITI PDQm Profile.
Overview
Actors
There are two actors in the PDQm profile:
- Patient Demographics Consumer queries the patient based on available demographics (search parameters) and gets the complete set of patient demographics in return (if there are any).
- Patient Demographics Supplier returns the complete set of available patient demographics based on the provided set of search parameters. The Founda Health Platform acts as the Patient Demographics Supplier in this profile.
Supported Transactions
There is one transaction defined within the PDQm profile:
- ITI-78: the Patient Demographics Supplier receives a request from the Patient Demographics Consumer to collect information about patients whose demographics data match data provided in the query parameters on the request message. The request is processed by the Patient Demographics Supplier and returns a response in the form of demographics information for the matching patients.
Mobile Patient Demographics Query (ITI-78)
The Founda Health Platform acts as a Patient Demographics Supplier to connected Clients of Application Providers that interact through the ITI-78 transaction. The transaction can be used to search for existing patients and retrieving the complete FHIR Patient Resource after the patient of interest has been identified.
Search for Patient Demographics
The transaction can be used to send either a GET or a POST request to search for existing patients.
GET Request
Send a GET request to endpoint https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Patient?<parameters>. Search parameters are added as key value pairs to the URL as described by the FHIR specification.
To indicate that the request and response should comply with ITI-78, the _profile parameter should be included to the search set: https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Patient?_profile=https://profiles.ihe.net/ITI/PDQm/ .
ο»ΏParameters
All parameters as listed in section 2:3.78.4.1.2.1 of the PDQm profile can be used as search parameters.
Parameter | Type | Required | Description |
_id | string | ο»Ώ | Resource (logical) identifier for the patient |
active | boolean | ο»Ώ | Search for active (true) or inactive (false) patients |
family | string | ο»Ώ | Family name or last name of the patient |
given | string | ο»Ώ | Given name of the patient |
identifier | token | ο»Ώ | A patient identifier, formatted as: <system>|<value>. Multiple identifiers can be added. |
telecom | token | ο»Ώ | Telecommunication details |
birthdate | date | ο»Ώ | Patient's birthday, e.g. "2000-10-01" |
address | string | ο»Ώ | A known address for the patient |
address-city | string | ο»Ώ | The city the patient lives in |
address-country | string | ο»Ώ | The country the patient lives in |
address-postalcode | string | ο»Ώ | The postal code of the patient's address |
address-state | string | ο»Ώ | The state the patient lives in |
gender | token | ο»Ώ | The patient's gender, from value set: http://hl7.org/fhir/R4/valueset-administrative-gender.html |
mothersMaidenName | string | ο»Ώ | The patient's mother's maiden name |
_profile | ο»Ώ | Yes | The profile transaction URL that the request is for, e.g. https://profiles.ihe.net/ITI/PDQm. |
An example patient demographics query
https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Patient?_family=lastname&given=firstname&_profile=https://profiles.ihe.net/ITI/PDQm/.
Response
When 0, 1, or N matching patient records are identified, the payload is a FHIR4 Bundle resource of type searchset.
Status code: 200 (OK)
An example response - one or more patients found:
An example response - patient not found:
When pagination is supported by the connected EHR, pagination URLs are included in the Bundle response.
Possible error responses
In case an error occurs during processing of the request, error codes 401, 404 are returned with an OperationOutcome that providers additional details.
ο»ΏStatus code: 401, 404
An example response - error:
POST Request
Send a POST request to endpoint https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Patient/_search. The Founda Health Platform will transform a POST request into a GET request, depending on the connected EHR capabilities.
Note that the request and response should comply with ITI-78, hence the Client should include the _profile parameter with the URL. ο»Ώ
The request body for the POST request should be of type application/x-www-form-urlencoded. The list of keys that can be included in this request is equal to the provided table for the GET request.
The keys of type string can also be used with an :exact modifier. Note that this is an optional part of the IHE PDQm profile specifications, which implies that not all EHRs might support it.
An example payload of POST Request:
An example response of an exact patient match:
Retrieve Patient Demographics
When a patient of interest has been identified in the response to a search request, the complete FHIR Patient Resource can be retrieved.
An example patient demographics query
https://api.eu.founda.com/1/health/organizations/{organizationId}/fhir/4/Patient/{resourceId}?_profile=https://profiles.ihe.net/ITI/PDQm/.
The _profile parameter should still be included to denote that it's an IHE PDQm-based retrieve request.
An example response of a FHIR Patient payload
ο»Ώ
