National Health Index FHIR API
View the NHI number and identity information of a health and disability service consumer.
Pātiki and Waharua Kōpito patterns
On this page
Brief Description
The purpose of the National Health Index (NHI), including the National Health Index number (NHI number), is to help with the planning, coordination and provision of health and disability support services across New Zealand.
The NHI number is the unique identifier for all patients who receive healthcare in NZ and is the cornerstone of clinical and administrative patient-related information. Very rarely do health providers rely on names alone for identifying patients. The NHI number identifies the patient for referrals, visits to the hospital, tests, medication prescriptions and patient-related correspondence. Correct identification of the patient is a critical aspect of clinical safety.
The NHI number ties together all patient information and patient systems. The NHI number is on patient labels, which are used on most items of patient documentation, from pharmaceutical labels to discharge summaries.
Where regional services exist, such as centralised diagnostic services, health providers may receive the diagnostic results electronically from an external source.
The NHI number is used to ensure that the results are associated with the correct patient.
For more information, please go here.
Overview
This is a FHIR API made up of two resources:
- NHIPatient, derived from the HL7 FHIR Patient resource.
- NHIAddress, derived from HL7 FHIR Address data type.
NHI numbers have one of 2 formats:
- AAANNNC (3 alpha, 3 numeric and one numeric check digit) – in current circulation
- AAANNAX (3 alpha, 2 numeric, 1 alpha and one alpha check digit). This format will be first issued circa 2025.
Accessible Data
The NHI holds the following information:
- name (including alternative names such as maiden names)
- NHI number
- address
- date of birth
- gender
- New Zealand citizenship status
- place of birth
- ethnicity
- date of death
The patient’s general practice and their phone and email contact details are not held in the NHI but are retrieved from the National Enrolment Service and NES Patient Preferences Service respectively, and returned along with the NHI details if the user has the correct permissions.
The Enrolled General Practitioner details may include:
- Enrolment id
- Period of enrolment
- HPI Practitioner
- HPI Organisation
- HPI Facility
The Contact details that may be returned include:
- Email address
- Home phone number
- Mobile phone number
Business functions and risk scores
To view what these risk scores mean, click here.
|
Name |
Function |
Description |
Clinical Risk Score |
Privacy Risk Score |
Security Risk Score |
Identity Risk Score |
|---|---|---|---|---|---|---|
|
Get Patient |
Get Patient using an NHI number |
Using a known NHI number, a GET Request is sent to the NHI, the request is validated and returns the patient data associated with the NHI number in the request. Returned results include a range of demographic data required to confirm identity — for example, name, gender, ethnicity, date and place of birth, address and New Zealand citizenship status. If the requester has the appropriate permissions the patient’s enrolled general practice and contact details, mobile, home phone and email are also included. |
HIGH |
HIGH |
HIGH |
Level 3 |
|
Get Patient - Enrolled GP |
Get Patient using an NHI number and include the patient’s enrolled GP in the response |
The patient’s enrolled GP information is returned in the patient resource |
HIGH |
HIGH |
HIGH |
Level 3 |
|
Get Patient - Contact details |
Get Patient using an NHI number and include the patient’s contact details in the response |
The patient’s contact details are returned in the patient resource. |
HIGH |
HIGH |
HIGH |
Level 3 |
|
Search Patient |
Search Patient using name, birthdate and other demographics |
A SEARCH Request is used when the NHI number is not known. The request is validated and data of patients matching the search criteria is returned in order of relevance. It returns only the core NHI fields (No enrolled GP or contact details even if the user has the correct permissions. Search parameters include, name, date of birth, gender, place of birth and address. |
HIGH |
HIGH |
HIGH |
Level 3 |
|
Maintain Patient |
Update Patient records |
Provided on a limited basis to primary and secondary healthcare providers, and health system data quality teams. Attribute dependent.
|
HIGH |
EXTREME |
HIGH |
Level 3 |
|
Create Patient |
Create Patient records |
Provided on a limited basis to primary and secondary healthcare providers. |
EXTREME |
EXTREME |
HIGH |
Level 3 |
|
Validate Patient |
Validate Patient using an NHI number and patient demographics |
A VALIDATE request is used when the NHI number and demographic details are known, but the requestor is not authorised to retrieve NHI details or they only need a match / no-match response. Validate parameters include NHI number, name, date of birth, gender, place of birth, and address. |
HIGH |
HIGH |
HIGH |
Level 3 |
Who can use this API
Health providers listed in Schedule 2 of the Health Information Privacy Code may access the information in the NHI.
This includes:
- Accident Compensation Corporation (ACC)
- Department of Corrections Health Services
- Health New Zealand | Te Whatu Ora
- Health Practitioners
- Hospitals
- Independent Practitioner Associations
- MedicAlert Foundation — New Zealand Incorporated
- Manatū Hauora — Ministry of Health
- New Zealand Blood and Organ Service
- New Zealand Defense Force Health Services
- Pharmaceutical Management Agency of New Zealand
- Primary Health Organisations (PHOs)
- Maori Health Authority
- Ministry for Disabled People
- Any health agency that has a contract or is funded by the above list to
Health New Zealand assigns appropriate permissions and monitors and audits the actions of health provider use of the NHI.
Use Cases
Suggestions on how to implement the NHI FHIR API.
- A new patient presents for healthcare
- A returning patient presents for healthcare
- A notification is received that patient details have changed.
- A provider notices a discrepancy between local and NHI record, but does not have update access.
- A user needs to validate an NHI number.
- Look up the patient’s enrolled General Practice (GP)
- Look up patient’s contact details
Multi API use cases
- National Health Index and Health Provider Index
- Lookup EDI for an enrolled patient’s General Practice
API Types
REST API
All REST API endpoints adhere to Fast Healthcare Interoperable Resources (FHIR) interoperability standards.
This is a FHIR API made up of two resources:
- NHIPatient, derived from the HL7 FHIR Patient resource.
- NHIAddress, derived from HL7 FHIR Address data type
Service Levels
Target 99.99% service availability 24x7.
Restrictions
Geo Restriction
GEO Restriction rules prevent access from clients with IPs located in countries other than those listed below. This is currently limited to:
- New Zealand
- Australia
- Canada
- Cook Islands
|
Plan |
Rate |
Burst |
Quota |
|
bronze |
1 request per second |
5 |
10,000 requests per day |
|
silver |
5 requests per second |
25 |
250,000 requests per day |
|
gold |
10 requests per second |
50 |
500,000 requests per day |
All test accounts will be assigned to the bronze usage plan. Production accounts will be assigned to the silver usage plan. If a Vendor wishes to be assigned to a higher plan, they should contact the us via the support form. Please request a change to the usage plan and make sure you include the ClientID at minimum (AppId and Orgid also recommended).
Guidelines
For general guidelines to implement this API, please click here.