Developer documentation‎ > ‎HL7 API‎ > ‎Messages‎ > ‎

QRY A19

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 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 ]   Who subject filter    


QRD-8.1 ID number (e.g. NHS number, or an MRN) 5637453543 If National ID:
[[Patient->National ID.Value]]

If Organisation Level ID:
[[Patient->Organisation Level ID.Value]]

If Team Level ID:
[[Patient->Team Level ID.Value]]
    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 ]
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
 

[ QRF-2 ]
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 ]
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:

1. An "open" query (return all active patients for this institute) -- just leave the search value in the QRD empty to get all fully-registered 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).

2. A timestamp-limited query (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|||||||||

3. 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||||

4. 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 Component Description Example Data Model
MSH

Message header. This conforms to PKB's standard definition.
 
MSA

Message acknowledgement
 

MSA-1
Acknowledgement code
 


MSA-1.1 Acknowledgement code. AA = accepted, AR = rejected, AE = error AA  

MSA-2
Message control ID. This is the MSH-10 value that was sent to PKB.
 


MSA-2.1 Message control ID ABC0000000001  
QRD

Query definition. A copy of the submitted QRD segment is returned.
 
[ QRF ]

Query filter. If a QRF segment was supplied, it will be returned.
 
{ [ PID ] }

Patient identification. One PID segment is returned for each matching patient.
 

{ [ PID-2 ] }
National IDs. The National ID Type used for the search will be the one associated with the country of the connecting organisation or team.
 


PID-2.1 National ID 5637453543 [[Patient->National ID.Value]]


PID-2.4 National ID assigning authority (e.g. "NHS" for the UK) NHS [[Patient->National ID->National ID Type.HL7 Assigning Authority]]


PID-2.5 National ID type code NH [[Patient->National ID->National ID Type.HL7 Type Code]]

{ [ PID-3 ] }
PID-3 contains a copy of the contents of PID-2
 

{ [ PID-4 ] }
PID-4 contains local identifiers
 


PID-4.1 Patient ID XYZ00001 If Organisation Level ID:
[[Patient->Organisation Level ID.Value]]

If Team Level ID:
[[Patient->Team Level ID.Value]]


PID-4.4 Patient ID assigning authority (e.g "NHS" for the UK) ABCHospital If Organisation Level ID:
[[Patient->Organisation Level ID->Organisation Level ID Type.HL7 Assigning Authority]]

If Team Level ID:
[[Patient->Team Level ID->Team Level ID Type.HL7 Assigning Authority]]


PID-4.5 Patient ID type code MR If Organisation Level ID:
[[Patient->Organisation Level ID->Organisation Level ID Type.HL7 Type Code]]

If Team Level ID:
[[Patient->Team Level ID->Team Level ID Type.HL7 Type Code]]

PID-5
Name
 


[ PID-5.1 ] Family name Smith [[Patient.Family Name]]


[ PID-5.2 ] Given name John [[Patient.Given Name]]

[ PID-7 ]
Date of birth
 


PID-7.1 Date of birth 19800101 [[Patient.Date of Birth]]

PID-11
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

QRY^A19: Query for patient registration status

Overview

This query can be used to retrieve a list of patients including registration status who are associated with your Organisation. A patient will be returned if there is a consent record (whether active or inactive) for any Team in your organisation.

Note: Self-registered patients that have not been activated will not be returned from an A19 query.

Definition

SegmentFieldComponentDescriptionExampleData Model
MSHMessage 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-7] Quantity Limited Request  
  QRD-7.1The result size to return before a DSC segment is introduced. 10000 
  QRD-7.2Must be 'RD' RD 

[ QRD-9 ]
"STA" to request results for all patients including registration status custom segment.
 


QRD-9.1What subject filterSTA 
  [QRD-11] Registration status filter.  
   QRD-11.1  

An optional registration status to filter results by when QRD-9.1 = STA.


Options:

REGISTERED

NOT_REGISTERED


If start timestamp (QRF-2.1) is specified then the query behaviour is to find patients where current registration status = specified value and where that status was set on or after the timestamp specified in QRF-2.1.


If there is no date restriction specified within the QRF segment then this is an open status query and results will be returned where current registration status = the value specified.

 REGISTERED 
[ QRF ]

Query filter
 

[ QRF-2 ]
Start timestamp. This will restrict the returned results to those patients whose record has been updated on or after this point in time.
 


QRF-2.1Start timestamp (inclusive). 201807012352 
  [QRF-5] Last seen patient identifier.  This should be used in conjunction with QRF-2.1 when a previous search response has been truncated and a DSC segment provided.

Providing the last seen patient identifier from the previous response allows the registration status query to be reinvoked from that last known point (QRF-2.1 + QRF-5.1).  

The last known patient identifier will not be returned in the response i.e. the search criteria is non inclusive.
  
   QRF-5.1 Public ID (UUID) for the corresponding patient1fd2a0f6-890b-4f68-9fa1-65342f649771 

Examples

PKB supports a few variations on the registration status (STA) query:

1. 
An open registration status query (return all patients including registration status) for your organisation
MSH|^~\&|App|SendingInst|HL7API|PKB|20190110140316||QRY^A19|ABC0000000001|P|2.4
QRD||||_queryId|||||STA

2. An open registration status query (return all patients including registration status) for your organisation. Limit results to 1000 records per query.
MSH|^~\&|App|SendingInst|HL7API|PKB|20190110140316||QRY^A19|ABC0000000001|P|2.4
QRD||||_queryId|||1000^RD||STA

3. 
A specific registration status query (return all patients with a registration state set to QRD-11) for your organisation
MSH|^~\&|App|SendingInst|HL7API|PKB|20190110140316||QRY^A19|ABC0000000001|P|2.4
QRD||||_queryId|||||STA|REGISTERED

4. 
A timestamp start and registration status specific query (return all patient records with a registration state set to and remaining at value specified in QRD-11 and where the record was updated since defined timestamp -- use the QRF filter to specify timestamp range).
MSH|^~\&|App|SendingInst|HL7API|PKB|20190110140316||QRY^A19|ABC0000000001|P|2.4
QRD||||_queryId|||||STA||REGISTERED
QRF||201811090000

5. A registration status query submitted following a previous truncated response. QRF-2.1 and QRF-5.1 are included as the last known values to search from.
MSH|^~\&|App|SendingInst|HL7API|PKB|20190110140316||QRY^A19|ABC0000000001|P|2.4
QRD||||_queryId|||||STA
QRF||
20181001235212.345+0000|||962cb105-8e95-41f1-9ebe-7761b8c5fd93

Response

PKB will respond with an ADR^A19 message.  t
his message returns the patient registration status information requested by a QRY^A19 message where QRD-9.1 =  "STA".
The response includes a custom ZID segment and potentially a DSC continuation pointer segment.  The returned patients will be sorted first by timestamp of change, and second by patient ID.

Definition

SegmentFieldComponentDescriptionExampleData Model
MSH

Message header. This conforms to PKB's standard definition.
 
MSA

Message acknowledgement
 

MSA-1
Acknowledgement code
 


MSA-1.1Acknowledgement code. AA = accepted, AR = rejected, AE = errorAA 

MSA-2
Message control ID. This is the MSH-10 value that was sent to PKB.
 


MSA-2.1Message control IDABC0000000001 
QRD

Query definition. A copy of the submitted QRD segment is returned.
 
[ QRF ]

Query filter. If a QRF segment was supplied, it will be returned.
 
{ [ PID ] }

Patient identification. One PID segment is returned for each matching patient.
 

{ [ PID-3 ] }
The patient identifiers.  A repeating list of national id and any additional local id's connected to the calling organisation
 


PID-3.1Patient ID5637453543If National ID:
[[Patient.National ID.Value]]

If Organisation Level ID:
[[Patient.Organisation Level ID.Value]]

If Team Level ID:
[[Patient.Team Level ID.Value]]


PID-3.4Patient ID assigning authority (e.g 'NHS')NHSIf National ID:
[[Patient.National ID.National ID Type.HL7 Assigning Authority]]

If Organisation Level ID:
[[Patient.Organisation Level ID.Organisation Level ID Type.HL7 Assigning Authority]]

If Team Level ID:
[[Patient.Team Level ID.Team Level ID Type.HL7 Assigning Authority]]


PID-3.5Patient ID type code. (e.g 'NH' for national id.)NHIf National ID:
[[Patient.National ID.National ID Type.HL7 Type Code]]

If Organisation Level ID:
[[Patient.Organisation Level ID.Organisation Level ID Type.HL7 Type Code]]

If Team Level ID:
[[Patient.Team Level ID.Team Level ID Type.HL7 Type Code]]

PID-5
Name
 


[ PID-5.1 ]Family nameSmith[[Patient.Family Name]]


[ PID-5.2 ]Given nameJohn[[Patient.Given Name]]

[ PID-7 ]
Date of birth
 


PID-7.1Date of birth19800101[[Patient.Date of Birth]]

PID-11
Address
 


[ PID-11.5 ]Postal codeSW1A 1AA
[[Patient.Postal Code]]
 { [ ZID ] }  Custom segment to return registration specific information. One ZID segment per corresponding PID segment.  
  ZID-1    
   ZID-1.1Public ID (UUID) for the corresponding PID segment.1fd2a0f6-890b-4f68-9fa1-65342f649771[[User.Public ID]]
  ZID-2

 
   ZID-2.1Registration status  REGISTERED [[Patient.Registered]]
  ZID-3

 
   ZID-3.1Last modified timestamp 20190101101112.123+0000
 [DSC]  Continuation pointer segment.  This will be returned if the number of results has exceeded the value specified by the caller in QRD-7.1 or has exceeded the server side max results setting.  

The calling organisation will need to recognise this segment and programmatically re-query with an amended start timestamp (QRF-2.1) based on the last seen timestamp (ZID-3) and the inclusion of a last seen patient (QRF-5.1) based on the last seen patient UUID (ZID-1.1).
  
   DSC-1.1 A UUID. Not to be used on subsequent calls.  


Examples

PKB responds to the QRY_A19 with a list of matching patients and their registration status. Minimal info for each patient is listed -- enough to match records (NHS num, name, DoB).

1. Response to query for all patient registration statuses

MSH|^~\&|HL7API|PKB|App|ReceivingInst|201901101100||ADR^A19|E|P|2.4
MSA|AA|ABC0000000001
QRD||||query1|||||STA
PID|||9444444444^^^NHS^NH||SMITH^MARJORIE||19700101||||^^^^CB1 1BC|
ZID|1fd2a0f6-890b-4f68-9fa1-65342f649771|REGISTERED|20180601235212.345+0000
PID|||9555555555^^^NHS^NH||DOE^JAMES||195001202||||^^^^CB1 8BL|
ZID|6e4ba6f5-8c6e-43b9-8de0-601ec833ee83|NOT_REGISTERED|201806012352
12.345+0000
PID|||9666666666^^^NHS^NH||BLOGGS^DAVID||195001202||||^^^^CB1 8BL|
ZID|9d90e773-dfe4-4c95-9690-d9b07c62f004|REGISTERED|201807012352
12.345+0000
PID|||977777777^^^NHS^NH||JONES^BOB||195001202||||^^^^CB1 8BL|
ZID|962cb105-8e95-41f1-9ebe-7761b8c5fd93|NOT_REGISTERED|201810012352
12.345+0000

2. Response to query for all patient registration statuses - result limit exceeded

MSH|^~\&|HL7API|PKB|App|ReceivingInst|201901101100||ADR^A19|E|P|2.4
MSA|AA|ABC0000000001
QRD||||query1|||1000^RD||STA
PID|||1000112C^^^MRN^HOSP~9444444444^^^NHS^NH||SMITH^MARJORIE||19700101||||^^^^CB1 1BC|
ZID|1fd2a0f6-890b-4f68-9fa1-65342f649771|REGISTERED|201806012352
12.345+0000
PID|||9555555555^^^NHS^NH||DOE^JAMES||195001202||||^^^^CB1 8BL|
ZID|6e4ba6f5-8c6e-43b9-8de0-601ec833ee83|NOT_REGISTERED|201806012352
12.345+0000
PID|||9666666666^^^NHS^NH||BLOGGS^DAVID||195001202||||^^^^CB1 8BL|
ZID|9d90e773-dfe4-4c95-9690-d9b07c62f004|REGISTERED|201807012352
12.345+0000
PID|||977777777^^^NHS^NH||JONES^BOB||195001202||||^^^^CB1 8BL|
ZID|962cb105-8e95-41f1-9ebe-7761b8c5fd93|NOT_REGISTERED|201810012352
12.345+0000
DSC|c4e61363-45c4-4a3d-a96e-777fe0f1e3e7

3. Response to query for all patients with a current registration status of REGISTERED

MSH|^~\&|HL7API|PKB|App|ReceivingInst|201901101100||ADR^A19|E|P|2.4
MSA|AA|ABC0000000001
QRD||||query1|||||STA||REGISTERED
PID|||1000112C^^^MRN^HOSP~9444444444^^^NHS^NH||SMITH^MARJORIE||19700101||||^^^^CB1 1BC|
ZID|1fd2a0f6-890b-4f68-9fa1-65342f649771|REGISTERED|201806012352
12.345+0000
PID|||9666666666^^^NHS^NH||BLOGGS^DAVID||195001202||||^^^^CB1 8BL|
ZID|9d90e773-dfe4-4c95-9690-d9b07c62f004|REGISTERED|201807012352
12.345+0000

4. Response to query for patients with a current registration status set to REGISTERED and where the record was updated on or after a defined start date

MSH|^~\&|HL7API|PKB|App|ReceivingInst|201901101100||ADR^A19|E|P|2.4
MSA|AA|ABC0000000001
QRD|||||||||STA||REGISTERED
QRF||201806290000
PID|||9666666666^^^NHS^NH||BLOGGS^DAVID||195001202||||^^^^CB1 8BL|
ZID|9d90e773-dfe4-4c95-9690-d9b07c62f004|REGISTERED|201807012352
12.345+0000
Comments