QRY A19 API Scope

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)

All of the patient’s national and org level IDs are returned, as well as their PKB public ID.

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.

Smith

[[Patient.Family name]]

 

 

 

 

QRD-8.3

Patient given name

John

[[Patient.Given name]]

 

 

 

 

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.

 

 

 

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

 

 

QRF-5

O

 

 

Date of birth

 

 

 

 

 

 

QRF-5

Date of birth

DOB=19900101

 

 

 

 

 

QRF-5

Email address

EMAIL=john-smith@test.com

 

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:
[[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

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 ] }

 

 

 

 

Patient identification. One PID segment per matching patient.

 

 

 

PID-2

 

 

 

The patient's national ID in the connecting organisation's own national ID scheme, where PKB holds one. If the organisation's country has several national ID schemes and PKB holds none in the organisation's own scheme, the first ID from PID-3 is returned here instead. Does not repeat. Empty if PKB holds no national ID for the patient.

4444444444^^^NHS^NH

 

 

 

 

 

PID-2.1

ID number

4444444444

 

 

 

 

 

PID-2.4

Assigning authority

NHS

 

 

 

 

 

PID-2.5

ID type code

NH

 

 

PID-3

 

 

 

Every national ID PKB holds for the patient in a scheme belonging to the connecting organisation's country. Countries with one national ID scheme (e.g. the UK) return a single ID here, the same value as PID-2. Countries with several (e.g. Canada, Australia) return all of them as repeats. Local IDs are not returned in this field — see PID-4.

PKB public ID is returned in this field with assigning authority PKB and type code PI.

5000147214^^^CANMB-MEH-JCR^PN~924919923^^^CANMB-MBH-JHI^JHNMB

 

 

 

 

 

PID-3.1

ID number

924919923

 

 

 

 

 

PID-3.4

Assigning authority

CANMB-MBH-JHI

 

 

 

 

 

PID-3.5

ID type code

JHNMB

 

 

PID-4

 

 

 

Local IDs: the patient's organisation-level IDs for the connecting organisation, followed by team-level IDs, as repeats. A team-level connection returns only that team's IDs; an organisation-level connection returns IDs for every team in the organisation.

 

 

 

 

 

 

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

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

R

 

 

Name

 

 

 

 

 

 

PID-5.1

Family name

Smith

[[Patient.Family Name]]

 

 

 

 

PID-5.2

Given name

John

[[Patient.Given Name]]

 

 

 

 

PID-5.5

Title

Mr

[[Patient.Title]]

 

PID-7

O

 

 

Date of birth

 

 

 

 

 

 

PID-7.1

Date of birth

19800101

[[Patient.Date of Birth]]

 

PID-8

O

 

 

Administrative sex

 

 

 

 

 

 

PID-8.1

Administrative sex

M

[[Patient.Administrative sex]]

 

PID-11

O

 

 

Address

 

 

 

 

 

 

PID-11.1

Address line 1

25 Maple Drive

[[Patient.Address line 1]]

 

 

 

 

PID-11.2

Address line 2

Bearsville

[[Patient.Address line 2]]

 

 

 

 

PID-11.3

City

Birmingham

[[Patient.City]

 

 

 

 

PID-11.4

County

West Midlands

[[Patient.County]]

 

 

 

 

PID-11.5

Postal code

SW1A 1AA

[[Patient.Postal Code]]

 

PID-13

O

 

 

Phone number and email addresses

 

 

 

 

 

 

PID-13.1

Telephone number / email address

0123456789

 

 

 

 

 

PID-13.2

Telecommunications use code

PRS

 

 

 

 

 

PID-13.3

Telecommunication equipment type

CP

 

 

PID-14

O

 

 

 

 

 

 

 

 

 

PID-14.1

Telephone number / email address

0748574857

 

 

 

 

 

PID-14.2

Telecommunications use code

WPN

 

 

 

 

 

PID-14.3

Telecommunication equipment type

PH

 

 

PID-15

O

 

 

Language

 

 

 

 

 

 

PID-15.1

Patient’s language

en

 

 

PID-29

O

 

 

Deceased Date

 

 

 

 

 

 

PID-29.1

Deceased Date

20260101

 

 

PID-30

O

 

 

Patient death indicator

 

 

 

 

 

 

PID-30.1

Death indicator

Y

 

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|4444444444^^^NHS^NH|1234567^^^ABCHospital^MR|SMITH^MARJORIE||19700101||||^^^^CB1 1BC
PID||5555555555^^^NHS^NH|5555555555^^^NHS^NH||DOE^JAMES||19500120||||^^^^CB1 8BL

Multiple-national-ID country (e.g. Canada). PID-2 carries the PHIN because that is the connecting organisation's scheme; PID-3 carries both national IDs; PID-4 carries the organisation-level ID:

MSH|^~\&|HL7API|PKB|CANMB-MEH-JCR|MEH|20260901185133+0000||ADR^A19|PKB-20260901185133+0000|P|2.4
MSA|AA|2026062318164199800
QRD|20260623181641|R|I|||||924919923^^^^^^^^CANMB-MBH-JHI^^^^JHNMB|DEM
PID||924919923^^^CANMB-MBH-JHI^JHNMB|5000147214^^^CANMB-MEH-JCR^PN~924919923^^^CANMB-MBH-JHI^JHNMB|00000804243^^^ME-HCS-1^RRI|SMITH^MARJORIE||19700101||||^^^^R2M 5E5

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.

A patient record will be repeated in the query response when a patient is in more than one Team within your Organisation. I.e. if a patient is in two teams then the response will include two pairs of PID/ZID segments for the one patient record. If the caller wishes to filter out the repeating results then they should inspect ZID-1.1 which is a unique UUID for a patient record (independent of Team association) and remove duplicates before processing the records locally.

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

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-5

O

 

 

Search parameters

 

 

 

QRD-7

O

 

 

Quantity Limited Request

 

 

 

 

 

 

QRD-7.1

The result size to return before a DSC segment is introduced. If a value greater than the system maximum is specified, the system maximum will be used instead. This is currently set to 10,000.

10000

 

 

 

 

 

QRD-7.2

Must be 'RD'

RD

 

 

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)

All of the patient’s national and org level IDs are returned, as well as their PKB public ID.

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.

Smith

[[Patient.Family name]]

 

 

 

 

QRD-8.3

Patient given name

John

[[Patient.Given name]]

 

 

 

 

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

 

 

"STA" to request results for all patients including registration status custom segment.

 

 

 

 

 

 

QRD-9.1

What subject filter

STA

 

 

QRD-11

O

 

 

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

O

 

 

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

Start timestamp (inclusive)

201507012352

 

 

QRF-5

O

 

 

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 patient

1fd2a0f6-890b-4f68-9fa1-65342f649771