QRY A19 API Scope
QRY A19: Query for patient demographics
Overview
This message can be used to retrieve a list of patients who have medical records in PKB and who are associated with your Organisation or Team.
Note: Self-registered patients that have not been activated will not be returned from an A19 query.
Definition
Segment | Field | Opt | RP/# | Component | Description | Example | Data Model |
|---|---|---|---|---|---|---|---|
MSH |
|
|
|
| Message header. This conforms to PKB's standard definition. |
|
|
QRD |
|
|
|
| Query definition |
|
|
| QRD-1 |
|
|
| Timestamp. We do not process this field. However, we will echo the value back to you in our response. |
|
|
| QRD-4 |
|
|
| Query ID. We do not process this field. However, we will echo the value back to you in our response. |
|
|
| QRD-8 | O |
|
| Who subject filter. This will be ignored if APN is provided in QRD-9. |
|
|
|
|
|
| QRD-8.1 | ID number (e.g. NHS number, or an MRN) | 5637453543 | If National ID: If Organisation Level ID: If Team Level ID: |
|
|
|
| QRD-8.2 | Patient family name. We do not process this field. However, we will echo the value back to you in our response. |
|
|
|
|
|
| QRD-8.3 | Patient given name. We do not process this field. However, we will echo the value back to you in our response. |
|
|
|
|
|
| QRD-8.13 | ID number type code. Use "MR" for a local number search. Otherwise, a National ID search is performed, regardless of what this value is. The National ID Type used for the search will be the one associated with the country of the connecting organisation or team. | NH |
|
| QRD-9 | O |
|
| Type of query to perform. Use "DEM" for demographics, or "APN" to request all active patients (including those without an ID). The default is "DEM". |
|
|
|
|
|
| QRD-9.1 | What subject filter | DEM |
|
[ QRF ] |
|
|
|
| Query filter. This will be ignored if APN is provided in QRD-9. |
|
|
| QRF-2 | O |
|
| Start timestamp. This will restrict the returned results to those patients activated or modified since the timestamp. |
|
|
|
|
|
| QRF-2.1 | Start timestamp (inclusive) | 201507012352 |
|
| QRF-3 | O |
|
| End timestamp. This will restrict the returned results to those patients activated or modified before the timestamp. |
|
|
|
|
|
| QRF-3.1 | End timestamp (exclusive) | 201507022351 |
|
Examples
PKB supports a few variations on this query:
An "open" query
To return all active patients for this institute, leave the search value in the QRD empty to get all active patients with national or hospital IDs:
MSH|^~\&|App|SendingInst|HL7API|PKB|20130219140316||QRY^A19|ABC0000000001|P|2.4||||||||
QRD|20130219140316|R|I|_3B30U4GM1|||||DEM||||
Alternatively, for debugging purposes you may want to see the full list of patients (including those that are still missing national and hospital IDs) -- to get this list, use “APN” instead of “DEM” in the QRD-9.1 field (note: queries filtering on patient name are not currently supported).
A timestamp-limited query
To return all active patients with a national or hospital ID set or modified in a timestamp range, use the QRF filter to specify timestamp range:
MSH|^~\&|App|SendingInst|HL7API|PKB|20130219140316||QRY^A19|ABC0000000001|P|2.4||||||||
QRD|20130219140316|R|I|_3B30U4GM1|||||DEM||||
QRF||201302191100|||||||||
A single patient query, with NHS number in the QRD
MSH|^~\&|App|SendingInst|HL7API|PKB|20130219140316||QRY^A19|ABC0000000001|P|2.4||||||||
QRD|20130219140316|R|I|_3B30U4GM1||||4444444444^^^^^^^^^^^^NH|DEM||||
A single patient query, with hospital ID number in the QRD
MSH|^~\&|App|SendingInst|HL7API|PKB|20130219140316||QRY^A19|ABC0000000001|P|2.4||||||||
QRD|20130219140316|R|I|_3B30U4GM1||||ABC12345^^^^^^^^^^^^MR|DEM||||
Note on ID-based queries: the type of ID search depends on the connecting institution and the QRD-8.13 field. If the QRD-8.13 value is “MR” the hospital ID for the connecting institution is searched. If the QRD-8.13 is any other value, the national ID for the country of the connecting institution is searched.
Response
PKB will respond with an ADR A19 message. This message returns the patient information requested by a QRY A19 message where QRD-9.1 = "DEM" or "APN".
Definition
Segment | Field | Opt | RP/# | Component | Description | Example | Data Model |
|---|---|---|---|---|---|---|---|
MSH |
|
|
|
| Message header. This conforms to PKB's standard definition. |
|
|
QRD |
|
|
|
| Query definition |
|
|
| QRD-1 |
|
|
| Timestamp. We do not process this field. However, we will echo the value back to you in our response. |
|
|
| QRD-4 |
|
|
| Query ID. We do not process this field. However, we will echo the value back to you in our response. |
|
|
| QRD-8 | O |
|
| Who subject filter. This will be ignored if APN is provided in QRD-9. |
|
|
|
|
|
| QRD-8.1 | ID number (e.g. NHS number, or an MRN) | 5637453543 | If National ID: If Organisation Level ID: If Team Level ID: |
|
|
|
| QRD-8.2 | Patient family name. We do not process this field. However, we will echo the value back to you in our response. |
|
|
|
|
|
| QRD-8.3 | Patient given name. We do not process this field. However, we will echo the value back to you in our response. |
|
|
|
|
|
| QRD-8.13 | ID number type code. Use "MR" for a local number search. Otherwise, a National ID search is performed, regardless of what this value is. The National ID Type used for the search will be the one associated with the country of the connecting organisation or team. | NH |
|
| QRD-9 | O |
|
| Type of query to perform. Use "DEM" for demographics, or "APN" to request all active patients (including those without an ID). The default is "DEM". |
|
|
|
|
|
| QRD-9.1 | What subject filter | DEM |
|
[ QRF ] |
|
|
|
| Query filter. This will be ignored if APN is provided in QRD-9. |
|
|
| QRF-2 | O |
|
| Start timestamp. This will restrict the returned results to those patients activated or modified since the timestamp. |
|
|
|
|
|
| QRF-2.1 | Start timestamp (inclusive) | 201507012352 |
|
| QRF-3 | O |
|
| End timestamp. This will restrict the returned results to those patients activated or modified before the timestamp. |
|
|
|
|
|
| QRF-3.1 | End timestamp (exclusive) | 201507022351 |
|
|
|
|
| PID-4.1 | Patient ID | XYZ00001 | If Organisation Level ID: If Team Level ID: |
|
|
|
| PID-4.4 | Patient ID assigning authority | ABCHospital | If Organisation Level ID: If Team Level ID: |
|
|
|
| PID-4.5 | Patient ID type code | MR | If Organisation Level ID: If Team Level ID: |
| PID-5 | R |
|
| Name |
|
|
|
|
|
| PID-5.1 | Family name | Smith | [[Patient.Family Name]] |
|
|
|
| PID-5.2 | Given name | John | [[Patient.Given Name]] |
| PID-7 | O |
|
| Date of birth |
|
|
|
|
|
| PID-7.1 | Date of birth | 19800101 | [[Patient.Date of Birth]] |
| PID-11 | O |
|
| Address |
|
|
|
|
|
| PID-11.5 | Postal code | SW1A 1AA | [[Patient.Postal Code]] |
Examples
PKB responds to the QRY A19 with a list of matching patients. Minimal info for each patient is listed -- enough to match records (NHS num, name, DoB).
MSH|^~\&|HL7API|PKB|App|ReceivingInst|201302201100||ADR^A19|ABC0000000002|P|2.4|
MSA|AA|ABC0000000001
QRD|201204201100|R|I|_3B30U4GM1|||||DEM||||
PID||4444444444^^^NHS^NH||1234567^^^ABCHospital^MR|SMITH^MARJORIE||19700101||||^^^^CB1 1BC
PID||5555555555^^^NHS^NH||2345678^^^ABCHospital^MR|DOE^JAMES||195001202||||^^^^CB1 8BL
Patients Know Best Wiki Hub | Deploy | Developer | Trust Centre | Manual | Research | Education | Release Notes
© Patients Know Best, Ltd. Registered in England and Wales Number: 6517382. VAT Number: GB 944 9739 67.
This API specification and design is licensed under a Creative Commons Attribution 4.0 International License.