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

Create Entitlement

Create Entitlement Overview

This operation is used to create a patient's entitlement for subsidised healthcare.

This operation is used to create an entitlement for:

• Community services card holders (CSC)
• Pharmaceutical subsidy card holders (PSC)

Scenarios for use

• CSC
  • A CSC entitlement is not returned with a search of the entitlements service, however a person presents with a CSC card. Note: Most CSC entitlements are automatically created when CSC details are recieved by Te Whatu Ora from work and income (Ministry of Social Development).
  • A CSC-dependent entitlement is not returned with a search of the entitlements service for a dependent child of a community services card holder.
• PSC
  • A family unit is eligible to recieve a PSC, and no PSC entitlement is returned with a search of the entitlements service.

Create Entitlement processing steps:

1. The user inputs details required to create the entitlement.
2. The integrating application sends a POST request to the NES Coverage endpoint with a payload containing the NesEntitlement resource to be created, excluding ids.
3. The request is validated - ALT: Validation failure. Operation Outcome resource returned
4. The Entitlement is created in the database and an ID is assigned.
5. A newly created NesEntitlement, including its ID, is returned to the client

Create Entitlement Request Example

create CSC Entitlement request

create PSC Entitlement request

Create entitlement rules and errors

Create CSC (community services card) entitlement rules and errors

For Request rules and errors click here

Rule	Error code	Error description	Error text	Http code
A create CSC entitlement request must include: type of entitlement beneficiary (NHI number of the patient) identifier (the entitlement card number) contained Patient resource organisation approving the entitlement (payor) status	EM07201	Is a required field	type is a required field beneficiary is a required field identifier is a required field contained patient is a required field payor is a required field status is a required field	400 Bad request
The contained patient must match Entitlement beneficiary, be alive, and validate with the National Health Index	EM02008 EM99999 EM99999	The patient identity information supplied does not match the patient identity information in the NHI N/A N/A	The patient identity information supplied does not match the patient identity information in the NHI. 'If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource' 'If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource' Patient NHI is required	422 Unprocessable Entity 400 Bad request 400 Bad request
A request to create an entitlement can be made against any valid NHI Identifier (live or dormant) for that patient.	EM02002	Cannot be found	NHI number supplied cannot be found	404 Not found
A Create Patient entitlement request must include a valid CSC Card Number	EM12006	The CSC Card Number must be known to Te Whatu Ora	The CSC Card Number must be known to MoH (Te Whatu Ora)	400 Bad request
A Patient can only be linked to 1 active Entitlement type i.e. CSC or CSCDependent	EM12001	The patient cannot have both CSC and CSCDependent Entitlements active at the same time	The patient cannot have both CSC and CSCDependent Entitlements active at the same time.	400 Bad request
A Patient can have a maximum of one Active CSC Entitlement.	EM12002	The patient cannot have more than one active CSC Entitlement.	The patient cannot have more than one active CSC Entitlement.	400 Bad request
A CSC Entitlement can only be associated to one (non-dependent) Patient	EM12003	The CSC Entitlement is already assigned to another patient	The CSC Entitlement is already assigned to another patient	400 Bad request
A patient can have multiple CSC dependent entitlements
A CSC Dependent entitlement can only be created for a person 18 or younger	EM12016	The patient is not a valid age to be a CSC Dependent.	The patient is not a valid age to be a CSC Dependent.	400 Bad request
PSC Payor must be set to Te Whatu Ora (Org ID - G0K357-H)	EM12029	Invalid Payor	Invalid Payor	400 Bad request

</table>

Create PSC (pharmaceutical subsidy card) entitlement rules and errors

For Request rules and errors click here

Rule	Error code	Error description	Error text	Http code
A create PSC entitlement request must include: type of entitlement beneficiary (NHI number of the patient) identifier (the entitlement card number) contained Patient resource organisation approving the entitlement (payor) status start date (period start)	EM07201	Is a required field	type is a required field beneficiary is a required field identifier is a required field contained patient is a required field payor is a required field status is a required field period start is a required field	400 Bad request
The contained patient must match Entitlement beneficiary, and validate with the National Health Index	EM02008 EM99999 EM99999	The patient identity information supplied does not match the patient identity information in the NHI. N/A N/A	The patient identity information supplied does not match the patient identity information in the NHI. 'If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource' 'If the resource is contained in another resource, it SHALL be referred to from elsewhere in the resource or SHALL refer to the containing resource' Patient NHI is required	422 Unprocessable Entity 400 Bad request 400 Bad request
Cannot create and entitlement for a deceased person	EM12022	Cannot create or update entitlement for deceased person	Cannot create or update entitlement for deceased person	400 Bad request
The PSC card number must be 1-16 numeric characters, with no leading zeros	EM12023	Invalid entitlement external id	Invalid entitlement external id	400 Bad request
A request to create an entitlement can be made against any valid NHI Identifier (live or dormant) for that patient.	EM02002	Cannot be found	NHI number supplied cannot be found.	404 Not found
A person can have multiple unique PSC entitlements (duplicates are not allowed)	N/A	N/A silent ignore	N/A silent ignore	N/A
PSC start date must not be a future date	EM07212	Cannot be a future date	Start date cannot be a future date
PSC Payor must be set to Te Whatu Ora (Org ID - G0K357-H)	EM12029	Invalid Payor	Invalid Payor	400 Bad request