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 Use Health Card (HUHC) and the Community Services Card (CSC). 


This FHIR API has 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 (e.g. child, parent, spouse, common law spouse, other, self or injured party). 
  • entitlement start date 
  • entitlement end date 
  • organisation approving the entitlement. 

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) 
  • Whaikaha - Ministry of Disabled People  
  • Any health agency that has a contract or is funded by any of the above to provide health and 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 are some example outcomes from using the NHI API. 

System to system 

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


  • A person can view their entitlement details 

Onboarding and implementation

To begin the onboarding process for this API, please visit the Consumer onboarding page.

For information on integrating, view the Implementation guide.

API type


All FHIR API endpoints adhere to Fast Healthcare Interoperable Resources (FHIR) interoperability standards and follow REST protocols.

Business functions and risk scores

To view what these risk scores mean, click here.





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. 







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. 







Level 3 


Geo restriction 
Geo restriction rules prevent access from clients with IPs located in countries other than those listed below. 

  • New Zealand 
  • Australia 
  • Canada 
  • Cook Islands 

Usage plan







1 request per second 


10,000 requests per day 


5 requests per second 


250,000 requests per day 


10 requests per second 


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