NHI Patient - New Zealand NHI IG v1.4.1

New Zealand NHI IG
1.4.1 - Release

New Zealand NHI IG - Local Development build (v1.4.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Resource Profile: NHI Patient

Official URL: http://hl7.org.nz/fhir/StructureDefinition/NhiPatient				Version: 1.4.1
Active as of 2024-01-24				Computable Name: NhiPatient

The Patient resource exposed by the NHI.

Describe the Patient resource exposed by the NHI

Core NHI Profile attributes

The NHI Patient resource represents the nationally held identity data for a patient.

This includes the core NHI Profile attributes:

name (including alternative names such as maiden names)
NHI number (live and any dormants)
address
date of birth
gender
New Zealand citizenship status
place of birth
ethnicity
date of death

The core NHI Profile attributes are returned to all users that have read and/or $match access to the NHI

Key differences from HL7 FHIR Patient specification

Ethnicity extension
NZ Citizenship extension
Dhb extension
Birthplace extension
Name
- information source extension
- preferred extension
- nhi-name-use-extra extension
Gender original text extension
Birthdate information source extension
Deceased date information source extension
Address
- nz-geocode extension
- suburb extension
- building-name extension
- domicile-code extension
- notValidatedAddressReason extension
- nz-address-id extension
- nz-address-derived extension

New NHI Number Format and check digit calculation

For more information click here for website links or click here for the consumer health identity standard, that includes the check digit calculation.

Patient’s General Practice

The details for a patient’s General Practice (GP) are returned in the NHI Patient Profile to users who have permission to access a patient’s National Enrolment Service (NES) information.

This is an additional permission required on your NHI FHIR account.

The NES details are maintained in real time in the NES database, which holds the relationship of a Patient (NHI number), to their GP Practice (hpi-organisation-id), GP clinic (hpi-facility-id) and where available the patient’s usual doctor (hpi-person-id / CPN).

Changes to the NES in October 2023 allows a patient’s GP Practice details to be recorded for both patients that are funded and also patients who are registered with a practice but not eligible for PHO funding. This change allows the Get Patient response to return the GP Practice details for both types of patients.

The expiry date for a registered patient is set to 01/01/2100 whereas the expiry date for an enrolled patient is never more than 3 years in the future.

For more information on what is available in the NES FHIR API please see NES UAT Implementation guide.

In the NHI the patient’s GP is only returned with a read on the resource. It is not returned in the $match response – even if a user has the correct permissions.

The patient version-id does not change when the GP changes. This is because the patient’s GP is not held in the NHI but is retrieved from the National Enrolment Service and returned along with the NHI details in the NHI Patient profile. The patient version-id only reflects changes to details held on the NHI.

For information on enrolment history, re-enrolment dates, enrolment status, or the last visit date (qualified encounter date) please subscribe to the NES.

A subset of the NES enrolment information is returned in the NHI FHIR GET response.

Enrolment information is returned in two places in the NHI patient profile:

the “generalPractitioner” attribute: This is the NES enrolment id.
the “contained” PractitionerRole resource: This holds the NES enrolment information as described below.

NES to FHIR mapping

FHIR attribute (PractitionerRole Resource)	NES Enrolment Information	Description
id	The NES enrolment id	Unique identifier of the patient's enrolment record. This will change when a patient transfers to a new practice, but will not reflect minor changes within an enrolment.
Period.start	enrolment.startDate	The date on which the Enrolment starts
Period.end	enrolment.expiryDate	The future date on which the Enrolment will expire.
Practitioner (reference / display)	Practitioner identifier (CPN) and name	The hpi-person-id (CPN) and name of the Practitioner who primarily provides the service to the person.
Organization (reference / display)	enrolling organisation ID and name	The hpi-organisation-id and name of the Organisation who the person enrols with for the Heath Service.
Location (reference / display)	Facility ID and name	The hpi-facility-id and name of the Facility where the person primarily receives the service.

Example of contained resource

"contained": [
        {
            "resourceType": "PractitionerRole",
            "id": "525599",
            "period": {
                "start": "2023-01-26T00:00:00+13:00",
                "end": "2026-01-26T00:00:00+13:00"
            },
            "practitioner": {
                "reference": "Practitioner/25ADNX",
                "display": "Dr Nick"
            },
            "organization": {
                "reference": "Organization/GAAAAA-0"
                "display": "Riviera Health Care"
            },
            "location": [
                {
                    "reference": "Location/FZZ862-H",
                    "display": "Dr Nick's Guaranteed Health Clinic"
                }
            ]
        }
    ]

Patient’s Contact details

The patient’s contact details are returned in the Patient.telecom attribute to users who have permission to access Patient Preferences. This is an additional permission required on your NHI FHIR account.

The contact details are only returned with a read on the resource. They are not returned in the $match response – even if a user has the correct permissions.

The patient version-id does not change when the patient’s contact details change. This is because the patient’s contact details are not held in the NHI but are retrieved from the National Enrolment Service and returned along with the NHI details in the NHI Patient profile. The Patient Version-id only reflects changes to details held on the NHI.

The information returned may include:

Email address
Home phone number
Mobile phone number

Example of Patient contact details

    "telecom": [
        {
            "system": "email",
            "value": "test.contact@testContact.com",
            "use": "home"
        },
        {
            "system": "phone",
            "value": "0275151510",
            "use": "mobile"
        },
        {
            "system": "phone",
            "value": "045882334",
            "use": "home"
        }

Usage:

Derived from this Resource Profile: Create NHI Patient
Examples for this Resource Profile: Patient/ZAA0792, Patient/ZAT2348, Patient/ZAT2496, Patient/ZJM9397 and Patient/ZKC4633

Formal Views of Profile Content

Description of Profiles, Differentials, Snapshots and how the different presentations work.

Differential Table
Key Elements Table
Snapshot Table
Statistics/References
All

This structure is derived from NzPatient

Name	Flags	Card.	Type	Description & Constraints
Patient	C	0..*	NzPatient	Information about an individual or animal receiving health care services nhi-nz-pat-1: only allows certain name name use values
Slices for contained		0..*	Resource	Contained, inline Resources Slice: Unordered, Closed by type:$this
contained:GP		0..1	PractitionerRole	Contained resource for the Patient's enrolled general Practitioner
extension:ethnicity		0..6	Nz_ethnicity	NZ Ethnicity
extension:nzCitizen		0..1	Nz_citizenship	This field indicates New Zealand citizenship status of the patient
extension:source		0..1	Extension	Extension
value[x]:valueCodeableConcept		0..1	CodeableConcept	Value of extension Binding: NZ Citizenship Information Source (required)
extension:domicile-code		0..0
extension:pho		0..0
extension:sex-at-birth		0..0
extension:iwi		0..0
birthPlace		0..1	(Complex)	Extension URL: http://hl7.org.nz/fhir/StructureDefinition/birth-place
Slices for identifier		0..*	Identifier	An identifier for this patient Slice: Unordered, Closed by value:system
identifier:All Slices				Content/Rules for all slices
type		0..0
period		0..0
identifier:NHI		0..*	Identifier	An identifier for this patient
type		0..0
period		0..0
active		0..0
name
extension		1..*	Extension	Extension
information-source		0..1	CodeableConcept	Information Source URL: http://hl7.org.nz/fhir/StructureDefinition/information-source Binding: Information Source (preferred)
value[x]:valueCodeableConcept		0..1	CodeableConcept	Value of extension Binding: Name Information Source (required)
preferred		1..1	boolean	Preferred URL: http://hl7.org/fhir/StructureDefinition/iso21090-preferred
nhi-name-use-extra		0..1	CodeableConcept	Extension URL: http://hl7.org.nz/fhir/StructureDefinition/name-use-extra Binding: NHI Name Use Extra (required)
use		0..1	code	temp \| nickname \| maiden
text		0..0
given		0..2	string	Given name and other given name(s)
prefix		0..*	string	Parts that come before the name Binding: Name Prefix Codes (required)
suffix		0..0
period		0..0
telecom		0..3	NzContactPoint	The Paient's contact details
extension:cp-purpose		0..0
system		0..1	code	phone \| email Binding: NHI ContactPoint System Codes (required)
use		0..1	code	home \| mobile Binding: NHI ContactPoint Use Codes (required)
rank		0..0
period		0..0
gender
Slices for extension		0..*	Extension	Extension Slice: Unordered, Open by value:url
originalText		0..1	string	Extension URL: http://hl7.org.nz/fhir/StructureDefinition/gender-original-text
birthDate
Slices for extension		0..*	Extension	Extension Slice: Unordered, Open by value:url
information-source		0..1	CodeableConcept	Information Source URL: http://hl7.org.nz/fhir/StructureDefinition/information-source Binding: Information Source (preferred)
value[x]:valueCodeableConcept		0..1	CodeableConcept	Value of extension Binding: Date of Birth Information Source (required)
deceased[x]		0..1	dateTime	Indicates if the individual is deceased or not
Slices for extension		0..*	Extension	Extension Slice: Unordered, Open by value:url
information-source		0..1	CodeableConcept	Information Source URL: http://hl7.org.nz/fhir/StructureDefinition/information-source Binding: Information Source (preferred)
value[x]:valueCodeableConcept		0..1	CodeableConcept	Value of extension Binding: Date of Death Information Source (required)
address		0..*	NhiAddress	An address expressed using postal conventions (as opposed to GPS or other location definition formats)
line		1..*	string	Street name, number, direction & P.O. Box etc.
maritalStatus		0..0
multipleBirth[x]		0..0
photo		0..0
contact		0..0
communication		0..0
generalPractitioner		0..1	Reference(PractitionerRole)	Reference for the Patient's enrolled general Practitioner
managingOrganization		0..0
link		0..0
Documentation for this format

Terminology Bindings (Differential)

Path	Conformance	ValueSet	URI
Patient.extension:nzCitizen.extension:source.value[x]:valueCodeableConcept	required	Nhi_citizenship_source `https://nzhts.digital.health.nz/fhir/ValueSet/nz-citizenship-source-code`
Patient.name.extension:information-source.value[x]:valueCodeableConcept	required	Nhi_name_source `https://nzhts.digital.health.nz/fhir/ValueSet/name-source-code`
Patient.name.prefix	required	Hpi_name_prefix `https://nzhts.digital.health.nz/fhir/ValueSet/name-prefix-code`
Patient.telecom.system	required	NhiContactPointSystem `https://nzhts.digital.health.nz/fhir/ValueSet/nhi-contact-point-system-code` from this IG
Patient.telecom.use	required	NhiContactPointUse `https://nzhts.digital.health.nz/fhir/ValueSet/nhiContactUseType` from this IG
Patient.birthDate.extension:information-source.value[x]:valueCodeableConcept	required	Nhi_date_of_birth_source `https://nzhts.digital.health.nz/fhir/ValueSet/date-of-birth-source-code`
Patient.deceased[x].extension:information-source.value[x]:valueCodeableConcept	required	Nhi_date_of_death_source `https://nzhts.digital.health.nz/fhir/ValueSet/dod-information-source-code`

Constraints

Id	Grade	Path(s)	Details	Requirements
nhi-nz-pat-1	error	Patient	only allows certain name name use values : Patient.name.where( (use.empty()) or (use='nickname') or (use = 'maiden') or (use = 'temp') )

Name	Flags	Card.	Type	Description & Constraints
Patient	C	0..*	NzPatient	Information about an individual or animal receiving health care services nhi-nz-pat-1: only allows certain name name use values
implicitRules	?!Σ	0..1	uri	A set of rules under which this content was created
Slices for contained		0..*	Resource	Contained, inline Resources Slice: Unordered, Closed by type:$this
contained:GP		0..1	PractitionerRole	Contained resource for the Patient's enrolled general Practitioner
ethnicity		0..6	CodeableConcept	NZ Ethnicity URL: http://hl7.org.nz/fhir/StructureDefinition/nz-ethnicity Binding: Ethnicity of a person (preferred)
nzCitizen		0..1	(Complex)	This field indicates New Zealand citizenship status of the patient URL: http://hl7.org.nz/fhir/StructureDefinition/nz-citizenship
extension:status		0..1	Extension	Extension
extension		0..0
url		1..1	uri	"status"
Slices for value[x]		0..1	CodeableConcept	Value of extension Slice: Unordered, Closed by type:$this
value[x]:valueCodeableConcept		0..1	CodeableConcept	Value of extension Binding: NZ Citizenship status (preferred)
extension:source		0..1	Extension	Extension
extension		0..0
url		1..1	uri	"source"
Slices for value[x]		0..1	CodeableConcept	Value of extension Slice: Unordered, Closed by type:$this
value[x]:valueCodeableConcept		0..1	CodeableConcept	Value of extension Binding: NZ Citizenship Information Source (required)
url		1..1	uri	"http://hl7.org.nz/fhir/StructureDefinition/nz-citizenship"
dhb		0..1	CodeableConcept	District Health Board linked to a NZ Healthcare Service, Location or Patient URL: http://hl7.org.nz/fhir/StructureDefinition/dhb Binding: District Health Board Identifer (extensible): NZ HPI-ORG Values for DHBs
birthPlace		0..1	(Complex)	Extension URL: http://hl7.org.nz/fhir/StructureDefinition/birth-place
modifierExtension	?!	0..*	Extension	Extensions that cannot be ignored
Slices for identifier	Σ	0..*	Identifier	An identifier for this patient Slice: Unordered, Closed by value:system
identifier:All Slices				Content/Rules for all slices
use	?!Σ	0..1	code	usual \| official \| temp \| secondary \| old (If known) Binding: IdentifierUse (required): Identifies the purpose for this identifier, if known .
identifier:NHI	Σ	0..*	Identifier	An identifier for this patient
use	?!Σ	0..1	code	usual \| official \| temp \| secondary \| old (If known) Binding: Valid use values for NHI (required)
system	Σ	1..1	uri	The namespace for the identifier value Fixed Value: https://standards.digital.health.nz/ns/nhi-id
telecom	C	0..3	NzContactPoint	The Paient's contact details
system	ΣC	0..1	code	phone \| email Binding: NHI ContactPoint System Codes (required)
use	?!Σ	0..1	code	home \| mobile Binding: NHI ContactPoint Use Codes (required)
deceased[x]	?!Σ	0..1	dateTime	Indicates if the individual is deceased or not
Slices for extension		0..*	Extension	Extension Slice: Unordered, Open by value:url
information-source		0..1	CodeableConcept	Information Source URL: http://hl7.org.nz/fhir/StructureDefinition/information-source Binding: Information Source (preferred)
extension		0..0
url		1..1	uri	"http://hl7.org.nz/fhir/StructureDefinition/information-source"
Slices for value[x]		0..1	CodeableConcept	Value of extension Slice: Unordered, Closed by type:$this
value[x]:valueCodeableConcept		0..1	CodeableConcept	Value of extension Binding: Date of Death Information Source (required)
address		0..*	NhiAddress	An address expressed using postal conventions (as opposed to GPS or other location definition formats)
nz-geocode		0..1	(Complex)	A geocode using the NZ specific datum (reference point) URL: http://hl7.org.nz/fhir/StructureDefinition/nz-geocode
suburb		0..1	string	The suburb part of the address URL: http://hl7.org.nz/fhir/StructureDefinition/suburb
building-name		0..1	string	The name of the building URL: http://hl7.org.nz/fhir/StructureDefinition/building-name
domicile-code		0..1	CodeableConcept	The domicile code associated with this address URL: http://hl7.org.nz/fhir/StructureDefinition/domicile-code Binding: Domicile Code (preferred)
notValidatedAddressReason		0..1	CodeableConcept	The reason an address was not validated URL: http://hl7.org.nz/fhir/StructureDefinition/not-validated-address-reason Binding: Address Not Validated Reason (preferred)
nz-address-id		0..1	string	Extension URL: http://hl7.org.nz/fhir/StructureDefinition/nz-address-id
nz-address-derived		0..1	(Complex)	Extension URL: http://hl7.org.nz/fhir/StructureDefinition/nhi-address-derived
use	?!Σ	0..1	code	home \| work \| temp \| old \| billing - purpose of this address Binding: NHI Address Use Codes (required) Example General: home
type	Σ	1..1	code	postal \| physical Binding: NHI Address Type Codes (required) Example General: both
line	Σ	1..*	string	Street name, number, direction & P.O. Box etc. This repeating element order: The order in which lines should appear in an address label Example General: 137 Nowhere Street
generalPractitioner		0..1	Reference(PractitionerRole)	Reference for the Patient's enrolled general Practitioner
Documentation for this format

Terminology Bindings

Path Conformance ValueSet URI

Patient.extension:nzCitizen.extension:status.value[x]:valueCodeableConcept

preferred

CitizenshipStatus

https://nzhts.digital.health.nz/fhir/ValueSet/nz-citizenship-status-code

Patient.extension:nzCitizen.extension:source.value[x]:valueCodeableConcept