PDQm

Source: https://profiles.ihe.net/ITI/PDQm/index.html

---

Table of Contents

1. PDQm
   • PDQm-Supporting Information
     • PDQm-Supported Identifiers
     • PDQm-Table0203
     • PDQm-Identifier Domains
     • PDQm-Table0002
     • PDQm-Important Links: FHIR
     • Health-interop sample identifiers
   • PDQm-HPRS-ITI-78
     • PDQm-ITI-78 Mobile Patient Demographics Query
     • PDQm-ITI-78 Examples
   • PDQm-HPRS-ITI-119
     • PDQm-ITI-119 Mobile Patient Demographics Query
     • PDQm-ITI-119 $match Examples
       • Search by HPRS-UUID
       • Search by HPRS-UUID error
       • Search by IdNumber error
       • Search by South African IDNumber
   • PDQm-Sandbox
     • PDQm-hprsintegrationv1.10
   • PDQm-Integration Methods

• PDQm-Integrator Checklist

---

PDQm

https://profiles.ihe.net/ITI/PDQm/index.html

PDQm-Supporting Information

• PDQm-Supported Identifiers
• PDQm-Table0203
• PDQm-Identifier Domains
• PDQm-Table0002
• PDQm-Important Links: FHIR
• Health-interop sample identifiers

PDQm-Supported Identifiers

The identifier is the only search parameter allowed. Within HPRS the following types of identifiers are supported for search:

Identifier Type	System Localisation	Identifier Type Code (Table0203)	ITI-119 Example (identifier subsection only)	ITI-78 Example	Notes
HPRS uuid	—	—	{"resource": {"resourceType": "Patient", "id": "7b553702-3b52-11ee-859a-43e31d42551f"}}	format: pdqm/Patient/<hprs-uuid> example: pdqm/Patient/7b553702-3b52-11ee-859a-43e31d42551f	If a patient is queried by their hprs id, the id is sent as part of the match post. No other identifiers should be sent.
South African Id Number	www.dha.gov.za	NNZAF	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF"}]}, "value": "6610280162082"}]	format: pdqm/Patient?identifier=www.dha.gov.za/nnzaf|<idnumber> example: pdqm/Patient?identifier=www.dha.gov.za/nnzaf|7804250694088	South African Id Numbers are validated before being used for a search: 13 digits in length, must be of form YYMMDD to begin, and end with a valid check digit
Asylum seeker - Section 22 permit	www.dha.gov.za	VP	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "VP"}]}, "value": "6610280162082"}]	format: pdqm/Patient?identifier=www.dha.gov.za/vp|<asylumpermitnumber> example: pdqm/Patient?identifier=www.dha.gov.za/vp|7804250694088	—
Passport number (South African and Foreign)	www.dha.gov.za	PPN	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "PPN"}]}, "value": "AS1234567"}]	format: pdqm/Patient?identifier=www.dha.gov.za/ppn|<passportnumber> example: pdqm/Patient?identifier=www.dha.gov.za/ppn|AS1234567	Passport numbers must be 9 or fewer characters and are reduced to alphanumeric characters only
Temporary permanent resident/refugee Id Number	www.dha.gov.za	TPR	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "TPR"}]}, "value": "6610280162082"}]	format: pdqm/Patient?identifier=www.dha.gov.za/tpr|<refugeeidnumber> example: pdqm/Patient?identifier=www.dha.gov.za/tpr|6610280162082	A refugee id number is validated the same way that a normal id number is validated
Legal refugee - Section 24 permit	www.dha.gov.za	VP	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "VP"}]}, "value": "PTAETH001590811"}]	format: pdqm/Patient?identifier=www.dha.gov.za/tpr|<refugeepermitnumber> example: pdqm/Patient?identifier=www.dha.gov.za/vp|PTAETH001590811	A refugee permit number is normally: <city of issue><country of origin><9 digit number>, e.g. PTAETH001590811
Facility File Number	https://test-hie.health.gov.za	MR	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR"}]}, "system": "https://test-hie.health.gov.za/mr/24...	format: pdqm/Patient?identifier=https://test-hie.health.gov.za/mr/<6 digit facility id>|<filenumber> example: pdqm/Patient?identifier=https://test-hie.health.gov.za/mr/242815|04801	When querying by a filenumber allocated by a specific facility, the facility key (6 digits) must be attached as per example. See https://dd.dhmis.org/orgunits.html?file=NIDS%20Integrated&source=nids&ver=0433
HPRN number	https://test-hie.health.gov.za	NH	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NH"}]}, "system": "https://test-hie.health.gov.za/nh", ...	format: pdqm/Patient?identifier=https://test-hie.health.gov.za/nh|<hprn number> example: pdqm/Patient?identifier=https://test-hie.health.gov.za/nh|1109087244	The HPRN is a 10 digit string.

PDQm-Table0203

HL7 Table 0203 (Identifier type)

Basic information: Table 0203, Type: HL7, Name: Identifier type

Detail: This table is used to encode the type of identifier linked to a patient.

HL7 v2.3.1

Value	Description
AM	American Express
AN	Account number
BR	Birth registry number
DI	Diner's Club card
DL	Driver's license number
DN	Doctor number
DS	Discover Card
EI	Employee number
EN	Employer number
FI	Facility ID
GI	Guarantor internal identifier
GN	Guarantor external identifier
LN	License number
LR	Local Registry ID
MA	Patient Medicaid number
MC	Patient's Medicare number
MR	Medical record number
MS	MasterCard
NE	National employer identifier
NH	National Health Plan Identifier
NI	National unique individual identifier
NNxxx	National Person Identifier where xxx is the ISO table 3166 3-character (alphabetic) country code
NPI	National provider identifier
PI	Patient internal identifier
PN	Person number
PRN	Provider number
PT	Patient external identifier
RR	Railroad Retirement number
RRI	Regional registry ID
SL	State license
SR	State registry ID
SS	Social Security number
U	Unspecified
UPIN	Medicare/CMS (formerly HCFA)'s Universal Physician Identification numbers
VN	Visit number
VS	VISA
WC	WIC identifier
XX	Organization identifier

HL7 v2.5

Value	Description
AM	American Express
AN	Account number
ANC	Account number Creditor
AND	Account number debitor
ANON	Anonymous identifier
ANT	Temporary Account Number
APRN	Advanced Practice Registered Nurse number
BA	Bank Account Number
BC	Bank Card Number
BR	Birth registry number
BRN	Breed Registry Number
CC	Cost Center number
CY	County number
DDS	Dentist license number
DEA	Drug Enforcement Administration registration number
DFN	Drug Furnishing or prescriptive authority Number
DI	Diner's Club card
DL	Driver's license number
DN	Doctor number
DO	Osteopathic License number
DPM	Podiatrist license number
DR	Donor Registration Number
DS	Discover Card
EI	Employee number
EN	Employer number
FI	Facility ID
GI	Guarantor internal identifier
GL	General ledger number
GN	Guarantor external identifier
HC	Health Card Number
IND	Indigenous/Aboriginal
JHN	Jurisdictional health number (Canada)
LI	Labor and industries number
LN	License number
LR	Local Registry ID
MA	Patient Medicaid number
MB	Member Number
MC	Patient's Medicare number
MCD	Practitioner Medicaid number
MCN	Microchip Number
MCR	Practitioner Medicare number
MD	Medical License number
MI	Military ID number
MR	Medical record number
MRT	Temporary Medical Record Number
MS	MasterCard
NE	National employer identifier
NH	National Health Plan Identifier
NI	National unique individual identifier
NII	National Insurance Organization Identifier
NIIP	National Insurance Payor Identifier (Payor)
NNxxx	National Person Identifier where xxx is the ISO table 3166 3-character (alphabetic) country code
NP	Nurse practitioner number
NPI	National provider identifier
OD	Optometrist license number
PA	Physician Assistant number
PCN	Penitentiary/correctional institution Number
PE	Living Subject Enterprise Number
PEN	Pension Number
PI	Patient internal identifier
PN	Person number
PNT	Temporary Living Subject Number
PPN	Passport number
PRC	Permanent Resident Card Number
PRN	Provider number
PT	Patient external identifier
QA	QA number
RI	Resource identifier
RN	Registered Nurse Number
RPH	Pharmacist license number
RR	Railroad Retirement number
RRI	Regional registry ID
SL	State license
SN	Subscriber Number
SR	State registry ID
SS	Social Security number
TAX	Tax ID number
TN	Treaty Number (Canada)
U	Unspecified identifier
UPIN	Medicare/CMS (formerly HCFA)'s Universal Physician Identification numbers
VN	Visit number
VS	VISA
WC	WIC identifier
WCN	Workers' Comp Number
XX	Organization identifier

PDQm-Identifier Domains

Basic information: https://hl7.org/fhir/R4/datatypes.html#Identifier

Detail: This table is used to detail the systems used with associated identifier types within the identifier object.

Structure

Name	Flags	Card.	Type	Description & Constraints
Identifier	Σ N		Element	An identifier intended for computation. Elements defined in Ancestors: id, extension
— use	?! Σ	0..1	code	usual | official | temp | secondary | old (If known) — IdentifierUse (Required)
— type	Σ	0..1	CodeableConcept	Description of identifier — IdentifierType (Extensible)
— system	Σ	0..1	uri	The namespace for the identifier value
— value	Σ	0..1	string	The value that is unique
— period	Σ	0..1	Period	Time period when id is/was valid for use
— assigner	Σ	0..1	Reference(Organization)	Organization that issued id (may be just text)

HL7 FHIR Local identifier domains

Value	Description
www.dha.gov.za	Department of Home Affairs - this namespaceid covers all identifiers issued by the DHA, identifiers should be distinguished by identifiertypecode.
https://test-hie.health.gov.za	Department of Health - this namespaceid covers all identifiers issued by the DOH, identifiers should be distinguished by identifiertypecode. (MR for filenumber (must also submit a facilityid), NH for HPRN)

PDQm-Table0002

HL7 Table 0002 (Marital Status)

Basic information: Table 0002, Type: HL7, Name: Marital Status

Detail: This table is used to encode the marital status of a patient.

HL7 v2.3.1

Value	Description
A	Separated
D	Divorced
M	Married
S	Single
W	Widowed
C	Common law
G	Living together
P	Domestic partner
R	Registered domestic partner
E	Legally Separated
N	Annulled
I	Interlocutory
B	Unmarried
U	Unknown
O	Other
T	Unreported

PDQm-Important Links: FHIR

• https://profiles.ihe.net/ITI/PDQm/index.html
• https://profiles.ihe.net/ITI/PDQm/ITI-78.html
• https://profiles.ihe.net/ITI/PDQm/ITI-119.html
• https://hl7.org/fhir/R4/patient.html
• HL7 v2 tables: https://hl7-definition.caristix.com/v2/HL7v2.5.1/Tables

FHIR libraries:

• nodejs: https://www.npmjs.com/package/fhir
• python: https://pypi.org/project/fhir.resources/
• c#: https://fire.ly/products/firely-net-sdk/
• java: https://hapifhir.io/

Health-interop sample identifiers

population_register_health resourceid

faa838b3-54df-663d-5c17-c9003b4f8e4f
3cc32d9e-7bd6-11e5-a548-cbec63e97c67
1146b878-6377-11e6-8f81-335bb35ea192
39802998-138d-11e7-9c4d-b3576e78533f
52737f92-8ace-11e6-b799-7f97b722daa5
93d67152-1a61-ac21-9f7e-f33af9004e10
c968967a-6eb3-03de-1623-1958c1262a54
24eaf046-3012-5a4c-065d-6571f9d6d19d
3c611850-c4b6-4feb-b971-fb939197b3db
dcbfc901-acb9-439d-4384-98cffa48a921
a267d6c9-ca26-4511-285b-ac941f083053
8a95bb58-0317-11e7-aeb8-57605183bf4d
4f43b037-e97d-82a9-167a-a8871ffaf046
9861b7aa-a6bc-11e4-93e4-cf2172a67042
9998a1c2-3493-ba1f-d745-e0ab0ffd42f9
066dd9ea-2ab4-80d2-cf04-4fd716e5fea7
cb7024dd-a556-21e1-5982-8c2cb418687f
25537d7c-8962-11e6-9fb0-a7036c50c064
71234634-d369-fe9a-73c3-b180088d89ee
fdfc30d3-877b-7177-561e-d92d0b3a7604

NNZAF (South African ID numbers)

1410040969081
1412255948081
1501120619081
1502165603089
1504255640088
1507035183089
1601200259087
1605220336080
1606025422083
1606041163083
3303036009087
3412100398084
3710060021087
5510080844080
6010045040089
6903036353083
7310285311086
7805190360086
7812025926081
8604125149089
8906071319081
9403195834087
9802205379084

NH (HPRN)

0010050755
0012706974
0023883549
0023958895
0031112824
0031332729
0038017471
0038045829
0041629932
0044122257
0044582963
0045589314
0069224418
0080145410
0087166039
0112375159
0114360621
0115656845
0116580143
0117415794
011749829514

PPN (Passport numbers)

01003775
01005123
01011252
01012810
01013600
01014238
01014239
01014418
01014602
01015535
00389751
00407523
004674
004850512
00534696
005637
00576911
0063487
00670109
00713928
00717858
00721457
007325
0075083
008370512
00870914
008970911
009004
009510
009667

VP Refugee

010166G813415M
010190435086
0102150786089
0104295276083
01051317
0105200079082
01068587
0107220864089
0109140556084
0109231163089
01100270899080
011110
0111150849086
015231121428
017131216125
017169114529
01718227732215

VP Asylum

PTAETH001590811
PTAMWI004911710
PTAZWE026591209
DBNCOD000260212
DBNCOD000350914
DBNCOD000650413
DBNCOD001300913
DBNUGA000060615
JHBMWI001000909
MUSCOD000280314
MUSCOD000370816
MUSCOD001090215
MUSWE000580217
MUSWE004000215
MUSZMB5630
NGA004110812
PTABGD000981214
PTACOD465140317
Ptacog004480312
PTAETH001590811
PTAETH920041108
PTAMWI001560514
PTAMWI002441013
PTAMWI004911710
PTANGA000660115
PTAWE000340816
PTAZWE001455367
PTAZWE002220515
PTAZWE004091216
PTAZWE005300914
PTAZWE023940617
PTAZWE026591209
PTAZWE031740816
PTAZWE058280410
PTAZWE093840610
PTAZWE107328722
PTAZWE140541104
PTAZWE284907563

MR with facility keys (fileNumber | key)

013102     | 483133
1864HETT   | 725415
00608DLA   | 612642
1866252677 | 640301
0144106879 | 640301
3062       | 804724
1616789754 | 640301
0106649023 | 640301
1982935007 | 640301
92870      | 941051
1954094007 | 640301
1804926796 | 640301
0031112824 | 640301
1766       | 668351
0066522673 | 640301
1409580246 | 640301
776        | 322306
7146       | 475724
0156440224 | 640301
16585      | 864451
4539       | 594342
0139694426 | 640301
0140621095 | 640301
3526       | 817551
860901TOM  | 483515

PDQm-HPRS-ITI-78

• PDQm-ITI-78 Mobile Patient Demographics Query
• PDQm-ITI-78 Examples

HPRS Implementation of ITI-78 (FHIR R4 query by parameter)

Author: Kirsten du Toit — Version: 1.0 — HPRS Version: 1.19.0 — 2025/11/12

PDQm-ITI-78 Mobile Patient Demographics Query

https://profiles.ihe.net/ITI/PDQm/ITI-78.html

REQUEST FORMAT

Query Patient Resource message: https://hl7.org/fhir/R4/search.html	HTTPS POST or GET — <base>/Patient?<parameters>
Retrieve Patient Resource message	HTTPS GET — <base>/Patient/<resourceid>
Content-type header	application/fhir+json, application/json+fhir, application/fhir+json, application/json, application/xml+fhir, application/fhir+xml, application/xml
X-security custom header	<RequestingApplication>$<UserId> — must be unique per user of the system. The requesting application is the name of the integrator or health software. The user id is the account id of the human requesting the information.
Supported parameters for search-query: identifier	identifier=<domain>/<identifierType>|<identifiervalue> (separated by a pipe) identifier=<domain>/mr/<facilitycode>|<identifiervalue> (separated by a pipe) identifier=<identifiervalue>

RESPONSE FORMAT

The FHIR standard provides encodings for responses as either XML or JSON.

If the query is a parameter based search, the response will be a bundle (https://hl7.org/fhir/R4/bundle.html) of resourceType Patient (https://hl7.org/fhir/R4/patient.html) in format as specified by HL7.

If the query is a read by id, the response will be a single Patient resource (https://hl7.org/fhir/R4/patient.html).

NOTE THE FOLLOWING

HPRS PDQm does NOT support the following from the IHE ITI-78 specification:

• 3.78.4.1.2.1 - only an identifier is supported as a parameter. OR and AND are not supported.
• 3.78.4.1.2.1.1 Combinations of search parameters
• 3.78.4.1.2.2 Parameter Modifiers
• 3.78.4.1.2.3 Populating Which Domains are Returned
• _format parameter (specified in Section 3.78.4.1.2.5). However a content-type header with a content-type as specified above is supported.
• 3.78.4.2.2.2 Mother's Maiden Name
• 3.78.4.2.2.4 Incremental Response Processing - Paging of Resource Bundle

PDQm-ITI-78 Examples

These requests must be sent with an empty body.

They should be a GET or a POST to https://test-hie.health.gov.za/pdqm/

Content-type can be set to be either xml or json:

application/fhir+json
application/json+fhir
application/fhir+json
application/json
application/xml+fhir
application/fhir+xml
application/xml

A custom security header is required: [x-security]:<requestingapplication>$<userid> (separated by a dollar)

Header	Value
x-security	emr$userid

Note that even though querying without specifying a domain is allowed, it may not necessarily return the expected patient.

All non-alphanumeric characters are stripped from the identifier value.

Successful Request examples:

Request	Expected response
https://test-hie.health.gov.za/pdqm/Patient/faa838b3-54df-663d-5c17-c9003b4f8e4f	Single Patient resource: {"resourceType": "Patient", "id": "faa838b3-54df-663d-5c17-c9003b4f8e4f", ...}
https://test-hie.health.gov.za/pdqm/Patient?identifier=www.dha.gov.za/nnzaf|1410040969081 https://test-hie.health.gov.za/pdqm/Patient?identifier=1410040969081	Bundle of one patient — "id": "799eaf83-302c-28b5-c509-198a89a3e90f"
https://test-hie.health.gov.za/pdqm/Patient?identifier=https://test-hie.health.gov.za/mr/483133|013102	Bundle of one patient — "id": "d8c2dc74-99be-11e6-879a-f3d2a94bcd70"
https://test-hie.health.gov.za/pdqm/Patient?identifier=www.dha.gov.za/vp|011110 https://test-hie.health.gov.za/pdqm/Patient?identifier=011110	Bundle of one patient — "id": "f6fe0a98-d194-11e6-b270-772e79ddda82"
https://test-hie.health.gov.za/pdqm/Patient?identifier=www.dha.gov.za/vp|PTAETH001590811 https://test-hie.health.gov.za/pdqm/Patient?identifier=PTAETH001590811	Bundle of one patient — "id": "30db77aa-9117-11e6-bb21-c39f4dbc1f65"
https://test-hie.health.gov.za/pdqm/Patient?identifier=www.dha.gov.za/ppn|008370512 https://test-hie.health.gov.za/pdqm/Patient?identifier=008370512	Bundle of one patient — "id": "ff32f600-6da8-11e7-940c-2bdeb0fa6582"
https://test-hie.health.gov.za/pdqm/Patient?identifier=https://test-hie.health.gov.za/nh|0010050755 https://test-hie.health.gov.za/pdqm/Patient?identifier=0010050755	Bundle of one patient — "id": "00d42c4a-3d30-11e6-963a-bf7b9ab5e345"
https://test-hie.health.gov.za/pdqm/Patient?identifier=myowntestdomain.csir.co.za/invalidtype|0010050755	Bundle of one patient — "id": "00d42c4a-3d30-11e6-963a-bf7b9ab5e345"

Unsuccessful Request examples:

Request	Expected response
https://test-hie.health.gov.za/pdqm/Patient/faa838b3-54df-663d-5c17-c9003b4f8e4d (patient id does not exist)	404 Not found with Operation Outcome object
https://test-hie.health.gov.za/pdqm/Patient?identifier=0010050755 (no security header)	403 Forbidden with Operation Outcome object - (Missing security header)
No accountid in security header (x-security: emr$)	403 Forbidden with Operation Outcome - (Missing account id in security header)
https://test-hie.health.gov.za/pdqm/Patient?identifier= https://test-hie.health.gov.za/pdqm/Patient? https://test-hie.health.gov.za/pdqm/Patient	400 Bad Request with Operation Outcome - (Invalid parameter)
https://test-hie.health.gov.za/pdqm/Location	<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Error</title></head><body><pre>Cannot GET /pdqm/Location</pre></body></html>
https://test-hie.health.gov.za/pdqm/Patient?identifier=www.dha.gov.za/nnzaf|1410040969085	422 Unprocessable entity with Operation Outcome - (Invalid RSA identification number)

PDQm-HPRS-ITI-119

• PDQm-ITI-119 Mobile Patient Demographics Query
• PDQm-ITI-119 $match Examples
  • Search by HPRS-UUID
  • Search by HPRS-UUID error
  • Search by IdNumber error
  • Search by South African IDNumber

HPRS Implementation of ITI-119 — PDQ (Patient Demographics Query)

Author: Kirsten du Toit — Version: 1.0 — HPRS Version: 1.10.0 — Date: 2025/11/12

PDQm-ITI-119 Mobile Patient Demographics Query

https://profiles.ihe.net/ITI/PDQm/ITI-119.html

REQUEST FORMAT

Query Patient Resource message: https://www.hl7.org/fhir/patient-operation-match.html

HTTPS POST — <base>/Patient/$match

Request Body: JSON ONLY.

Note that only identifier values are included in the search. Other demographic parameters are ignored in the matching process.

If an id is supplied for the Patient resource it is assumed to be the hprsuuid (resourceid requested). An error will be returned if there are identifier parameters.

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {
            "use": "usual",
            "type": {
              "coding": [
                {
                  "system": "http://hl7.org/fhir/v2/0203",
                  "code": "MR"
                }
              ]
            },
            "system": "urn:oid:1.2.36.146.595.217.0.1",
            "value": "12345"
          }
        ]
      }
    },
    {
      "name": "count",
      "valueInteger": "3"
    },
    {
      "name": "onlyCertainMatches",
      "valueBoolean": "false"
    }
  ]
}

Content-type header	application/fhir+json, application/json+fhir, application/fhir+json, application/json
X-security custom header	<RequestingApplication>$<UserId> — must be unique per user of the system. The requesting application is the name of the integrator or health software. The user id is the account id of the human requesting the information.

OR resource.metadata — note that the codes must match those in the example or the security metadata will not be recognised:

"meta": {
  "security": [
    {
      "system": "emr.health.gov.za/accounts",
      "code": "USERID",
      "display": "theuser"
    },
    {
      "system": "ipaddress",
      "code": "IPADDRESS",
      "display": "146.64.19.84"
    }
  ]
}

Supported parameters for search-query: identifier

RESPONSE FORMAT

The FHIR standard provides encodings for responses as either XML or JSON.

If the query is a parameter based search, the response will be a bundle (https://hl7.org/fhir/R4/bundle.html) of resourceType Patient (https://hl7.org/fhir/R4/patient.html) in format as specified by HL7.

If the query is a read by id, the response will be a single Patient resource (https://hl7.org/fhir/R4/patient.html).

NOTE THE FOLLOWING

HPRS PDQm does NOT support the following from the IHE ITI-119 specification:

• 3.119.4.1.2 Message Semantics - count and onlycertainmatches are not yet implemented
• 3.119.4.1.2.1 Populating Expected Response Format — XML is not supported as a request format
• 3.119.4.2.2.2 Mother's Maiden Name
• 3.78.4.2.2.4 Incremental Response Processing - Paging of Resource Bundle

PDQm-ITI-119 $match Examples

• Search by HPRS-UUID
• Search by HPRS-UUID error
• Search by IdNumber error
• Search by South African IDNumber

All the searches below can take place as parameter requests or as a single patient resource request. See examples of both request types in the "Search by South African Id" example.

Search By	Successful Requests (subsection of body)	Successful Response expected
South African idnumber	"identifier": [{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF"}]}, "system": "https://test-hie.health.gov.za/nnzaf", "value": "1412255948081"}]	Bundle of 1 Patient Resource — "id": "23bc99d8-c88b-11e4-9d31-33850982e90f"
Passport number	{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "PPN"}]}, "system": "www.dha.gov.za", "value": "01011252"}	Bundle of 1 Patient Resource — "id": "f8c16520-6535-11e7-81a5-9b7b14298206"
National Health Number (HPRN)	{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NH"}]}, "system": "https://test-hie.health.gov.za", "value": "0114360621"}	Bundle of 1 Patient Resource — "id": "00b3b7bd-0ce7-637a-62d9-de5b91a99883"
Refugee or asylum permit	{"type": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "VP"}]}, "system": "www.dha.gov.za", "value": "PTAZWE026591209"}	Bundle of 1 Patient Resource — "id": "99da7cf8-08a2-11e7-99b0-677fba34843f"

Search by medical file number (must have facility key)

{
  "resourceType": "Patient",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MR"
          }
        ]
      },
      "system": "https://test-hie.health.gov.za/mr/483133",
      "value": "013102"
    }
  ],
  "meta": {
    "security": [
      { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
      { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
    ]
  }
}

Response: Bundle of 1 Patient Resource — "id": "2acdc2d6-9f46-11e6-b77d-c3c608a3dc39"

Search by resource id (HPRS UUID)

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "52737f92-8ace-11e6-b799-7f97b722daa5",
        "meta": {
          "security": [
            { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
            { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
          ]
        }
      }
    }
  ]
}

Response: Single Patient resource — "id": "52737f92-8ace-11e6-b799-7f97b722daa5"

Single patient resource as the body (not parameter request)

{
  "resourceType": "Patient",
  "id": "52737f92-8ace-11e6-b799-7f97b722daa5",
  "meta": {
    "security": [
      { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
      { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
    ]
  }
}

Response: Single Patient resource — "id": "52737f92-8ace-11e6-b799-7f97b722daa5"

Single patient resource with security header instead of security segment

{
  "resourceType": "Patient",
  "id": "52737f92-8ace-11e6-b799-7f97b722daa5"
}

Response: Single Patient resource — "id": "52737f92-8ace-11e6-b799-7f97b722daa5"

Unsuccessful Requests

Scenario	Expected response
Patient does not exist (NNZAF 4204200335085)	404 Not Found with a (patient not found) operation outcome
Missing security segment and security header	403 Forbidden with an Operation Outcome (missing security segment)
Invalid identifier type code (PRV)	400 Bad Request with Operation Outcome (Invalid identifier type code)
Missing facility key in MR system (https://test-hie.health.gov.za/mr/)	400 Bad Request - Operation Outcome (Invalid identifier system required https://test-hie.health.gov.za/mr/<facilitycode> - missing facility key)
Request with both an id and an identifier - potential conflicting identifiers	422 Unprocessable Entity - OperationOutcome ("Conflicting identifier values in the request, request cannot contain both a patient id and an identifier")

Search by HPRS-UUID

POST https://test-hie.health.gov.za/pdqm/Patient/$match

REQUEST (type: parameters)

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
      "resource": {
        "resourceType": "Patient",
        "id": "52737f92-8ace-11e6-b799-7f97b722daa5",
        "meta": {
          "security": [
            { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
            { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
          ]
        }
      }
    }
  ]
}

OR REQUEST (type: patient)

{
  "resourceType": "Patient",
  "id": "52737f92-8ace-11e6-b799-7f97b722daa5",
  "meta": {
    "security": [
      { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "TheUser" },
      { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
    ]
  }
}

OR REQUEST (type: patient without meta security but with x-security custom header)

{
  "resourceType": "Patient",
  "id": "52737f92-8ace-11e6-b799-7f97b722daa5"
}

RESPONSE

{
  "resourceType": "Patient",
  "id": "52737f92-8ace-11e6-b799-7f97b722daa5",
  "identifier": [
    {
      "use": "official",
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }],
        "text": "Active National Person Identifier - South Africa"
      },
      "system": "www.dha.gov.za/nnzaf",
      "value": "0604256558080",
      "period": { "start": "2018-02-21" }
    },
    {
      "use": "official",
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }],
        "text": "Inactive National Person Identifier - South Africa"
      },
      "system": "www.dha.gov.za/nnzaf",
      "value": "0604256558080",
      "period": { "end": "2018-03-13" }
    },
    {
      "use": "official",
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }],
        "text": "Inactive National Person Identifier - South Africa"
      },
      "system": "www.dha.gov.za/nnzaf",
      "value": "0604256558080",
      "period": { "end": "2018-03-15" }
    },
    {
      "use": "secondary",
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NH" }],
        "text": "Active Patient Record Number (National Health Plan Identifier)"
      },
      "system": "https://test-hie.health.gov.za/nh",
      "value": "1817211244",
      "period": { "start": "2016-10-05" }
    },
    {
      "use": "secondary",
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" }],
        "text": "Active File number for a facility"
      },
      "system": "https://test-hie.health.gov.za/mr/271460",
      "value": "1817211244",
      "period": { "start": "2018-02-15" },
      "assigner": { "display": "nc Hanover Clinic" }
    },
    {
      "use": "secondary",
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" }],
        "text": "Active File number allocated by the National Department of Health"
      },
      "system": "https://test-hie.health.gov.za/mr",
      "value": "1817211244",
      "period": { "start": "2016-10-05" },
      "assigner": { "display": "DoH (REPUBLIC OF SOUTH AFRICA Department of Health)" }
    }
  ],
  "active": true,
  "name": [
    { "family": "NKADIMENG", "given": ["MARIET"] }
  ],
  "telecom": [
    { "system": "email", "value": "NK.MA@TESTING.COM" },
    { "system": "phone", "value": "0000077194" }
  ],
  "gender": "male",
  "birthDate": "2006-04-25",
  "deceasedBoolean": false,
  "address": [
    {
      "use": "home",
      "type": "both",
      "line": ["LAERSKOOL BYSONDERHEID", "VAN ROOYVENWEG ROEDTAN 580"],
      "postalCode": "7005"
    }
  ],
  "contact": [
    {
      "relationship": [
        {
          "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0131", "code": "N" }],
          "text": "MOTHER"
        }
      ],
      "name": { "family": "MANDERS", "given": ["MILLIE"] },
      "telecom": [{ "system": "phone", "value": "0000006576", "use": "home" }],
      "address": {
        "use": "home",
        "type": "both",
        "line": ["THE HILLS", "HANOVER DISTRICT"],
        "city": "HANOVER",
        "state": "WESTERN CAPE",
        "postalCode": "7005"
      }
    }
  ]
}

Search by HPRS-UUID error

POST https://test-hie.health.gov.za/pdqm/Patient/$match

REQUEST

{
  "resourceType": "Patient",
  "id": "7b553702-3b52-11ee-859a-43e31d42551f",
  "identifier": [
    {
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NH" }]
      },
      "value": "1464607843"
    }
  ],
  "meta": {
    "security": [
      { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "TheUser" },
      { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
    ]
  }
}

RESPONSE — HTTP 422 Unprocessable Entity

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1",
            "code": "CONFLICTING_VALUES",
            "display": "Conflicting identifier values"
          }
        ],
        "text": "Conflicting identifier values in the request, request cannot contain both a patient id and an identifier"
      }
    }
  ]
}

Search by IdNumber error

POST https://test-hie.health.gov.za/pdqm/Patient/$match

Request — searching with an invalid South African id number

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {
            "type": {
              "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }]
            },
            "system": "https://test-hie.health.gov.za/nnzaf",
            "value": "4204200335085"
          }
        ],
        "meta": {
          "security": [
            { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
            { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
          ]
        }
      }
    }
  ]
}

OR send request body as a single resource

{
  "resourceType": "Patient",
  "identifier": [
    {
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }]
      },
      "system": "https://test-hie.health.gov.za/nnzaf",
      "value": "4204200335082"
    }
  ],
  "meta": {
    "security": [
      { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
      { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
    ]
  }
}

RESPONSE — HTTP 422 Unprocessable Entity

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1",
            "code": "INVALID_PARAMETER",
            "display": "Invalid parameter"
          }
        ],
        "text": "Invalid RSA identification number."
      }
    }
  ]
}

Search by South African IDNumber

POST https://test-hie.health.gov.za/pdqm/Patient/$match

Request

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
      "resource": {
        "resourceType": "Patient",
        "identifier": [
          {
            "type": {
              "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }]
            },
            "system": "https://test-hie.health.gov.za/nnzaf",
            "value": "1502165603089"
          }
        ],
        "meta": {
          "security": [
            { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
            { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
          ]
        }
      }
    }
  ]
}

OR send request body as a single resource

{
  "resourceType": "Patient",
  "identifier": [
    {
      "type": {
        "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }]
      },
      "system": "https://test-hie.health.gov.za/nnzaf",
      "value": "1502165603089"
    }
  ],
  "meta": {
    "security": [
      { "system": "emr.health.gov.za/accounts", "code": "USERID", "display": "theuser" },
      { "system": "ipaddress", "code": "IPADDRESS", "display": "146.64.19.84" }
    ]
  }
}

Response

{
  "resourceType": "Bundle",
  "meta": {
    "profile": [
      "http://nextgen.meraka.csir.co.za.github.io/ddcc/StructureDefinition/DDCCRetrieveHealthEventResponse"
    ]
  },
  "type": "batch-response",
  "id": "12fb8703-041d-461f-94f9-90c9b25cf3e1",
  "timestamp": "2025-11-14T14:13:40.929Z",
  "types": "searchset",
  "total": 1,
  "link": [
    { "relation": "self", "url": "https://test-hie.health.gov.za/pdqm/Patient/$match" }
  ],
  "entry": [
    {
      "fullUrl": "https://test-hie.health.gov.za/beneficiaries/01094436-d830-11e4-b274-1b767ccd377d",
      "resource": {
        "resourceType": "Patient",
        "id": "01094436-d830-11e4-b274-1b767ccd377d",
        "identifier": [
          {
            "use": "official",
            "type": {
              "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "NNZAF" }],
              "text": "Active National Person Identifier - South Africa"
            },
            "system": "www.dha.gov.za/nnzaf",
            "value": "1502165603089",
            "period": { "start": "2019-04-10" }
          }
        ],
        "active": true,
        "name": [
          { "family": "HLONGWANE", "given": ["THABISO"] }
        ],
        "telecom": [
          { "system": "email", "value": "HL.TH@TESTING.COM" },
          { "system": "phone", "value": "0000096834" }
        ],
        "gender": "male",
        "birthDate": "2015-02-16",
        "deceasedBoolean": false,
        "address": [
          {
            "use": "home",
            "type": "both",
            "line": ["MAPHOPHE PRIMARY", "SASELAMANI MHINGA TRIBAL"]
          }
        ]
      },
      "search": {
        "extension": [
          {
            "url": "https://hl7.org/fhir/extensions/CodeSystem-match-grade.html",
            "valueCode": "certain"
          }
        ],
        "mode": "match",
        "score": 1
      }
    }
  ]
}

PDQm-Sandbox

PDQm-hprsintegrationv1.10

HPRS integration sandbox details

Author: Kirsten du Toit — Version: 1.0 — Date: 2025/11/14

HPRS INTEGRATION SANDBOX ACCESS

URL: https://test-hie.health.gov.za/pdqm

PDQ ACCESS:

All PDQ requests whether to HPRS central or to HPRS local use Mutual TLS Https. Health-interop is setup to work with both mutual TLS (certificate that we sign for you) and without mutual TLS (still using https, but not sending a certificate). Note that this is only for testing. A certificate is REQUIRED for connection to production central.

Optionally Secured HTTPS traffic (Mutual TLS): URL: https://test-hie.health.gov.za/pdqm

Note that a security header is required for ITI-78 and either a security header or the meta security segment for ITI-119.

Use the Patient Idnumber, HPRS uuid, FileNumber, PRN to query via pdq.

WORKING PDQ EXAMPLES: See separate document

TEST TOOL: POSTMAN in order to create an http post for testing the PDQ query and response.

PDQm-Integration Methods

The following integration methods are available for testing on health-interop:

Service name	Protocol	Port Number	Url	Mutual TLS
hprs-local-pix-pdq-service-https (ER7 pipe hat string HL7 v2.5)	HTTPS	443	https://test-hie.health.gov.za/pdq	Optional
pdqm-iti-78 / pdqml-iti-119 (FHIR HL7 R4)	HTTPS	443	https://test-hie.health.gov.za/pdqm	Optional

For the purposes of testing, mutual TLS is optional in order to test against https://test-hie.health.gov.za/pdq and pdqm. However a certificate is required for connection to production HPRS central or facility versions.

Normal Points of message definition conformance failure:

1. Missing x-security header for ITI-78 requests.
2. Missing meta security data for ITI-119 requests.
3. Missing ATNA logging.
4. Inability to handle Error cases.