Overview

This is a FHIR API made has of two resources: 

  • Patient Entitlements, derived from the HL7 FHIR coverage resource. 
  • Patient Enrolments, derived from the HL7 FHIR episode of care resource. 

Accessible Data

The NES entitlement API holds the following information: 

  • Identifier – external entitlement ID 
  • Beneficiary – NHI number 
  • Entitlement Type 
  • Entitlement status 
  • Relationship – The relationship between the Subscriber and the Beneficiary (eg. child, parent, spouse, common law spouse, other, self or injured party) 
  • Entitlement start date 
  • Entitlement end date 
  • Organisation approving the entitlement 

Business functions and risk scores

Name 

Function 

Description 

Clinical Risk Score 

Privacy Risk Score 

Security Risk Score 

Identity Risk Score 

READ Entitlement 

Get Entitlement using valid Entitlement-id 

The Get Entitlement operation allows an authorised user to retrieve an Entitlement record for a Patient using a known Entitlement record id. 

LOW 

2 

EXTREME 

10 

HIGH 

18 

Level 3 

Search Entitlement using an NHI number  

This is typically used to get all entitlements for a patient. 

Create Entitlement 

Create Entitlement 

This operation records a patient’s entitlement to some form of subsidised healthcare. 

MEDIUM 

8 

EXTREME 

11 

HIGH 

18 

Level 3 

Brief Description

Entitlements is a resource available from within the National Enrolment Service.  The National Enrolment Service (NES) is a registry designed to provide a single source of truth for patient enrolments, entitlements and newborn enrolment nominations.   

The NES system also has the capability to store and disseminate details relating to a patient’s entitlements. At the current time two such entitlements are recorded in NES – the High User Health Card (HUHC) and the Community Services Card (CSC). 

For more information, please go here.

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 provide health or disability services. 

Health New Zealand assigns appropriate permissions and monitors and audits the actions of health provider use of the NHI. 

Use Cases

The below lists a few example outcomes that can be achieved when using the NHI API. 

System to System 

  • Search the Entitlement details using known entitlement ID 
  • Lookup the what entitlements a patient has subscribed to 
  • Create a new Entitlement for a patient  

Patient 

  • A person view their Entitlement details 

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 

Usage plan

  

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 please go 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.