New Zealand NES IG - Local Development build (v1.4.7-snapshot) 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)

Additional information

CSC

• The create CSC operation should be used when:
  • a CSC entitlement is not returned with a search of the entitlements service however a person presents with a CSC. In this scenario the NHI match service hasn't been able to match an NHI to a CSC provided by MSD. The create matches the NHI with the CSC information provided by MSD and creates the entitlement. Most CSC entitlements are automatically created when CSC details are recieved.
  • A CSC-dependent entitlement is not returned with a search of the entitlements service for a dependent child of a community services card holder. In this case the create operation is used to create and entitlement for the dependent child. The dependent childs CSC entitlement will have the same card number as the parent. The FHIR service uses the relationship attributre to denote a dependent card holder.

PSC

• The create PSC operation should be used when an individual or family unit is eligible to recieve a PSC and no PSC entitlement is returned with a search of the entitlements service.
• When creating a PSC the entitlements service will automatically generate a PSC number (identifier) for an individual or the first member of the family unit. For each subsequent member of the family unit, the PSC number (identifier) provided by the entitlement service should be included in the create operation. This will result in all members of the family have the same card number (Not they will all have their own entitlements and therefore have individual entitlement IDs (Coverage.id)).

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

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

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) 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 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
A Create PSC Entitlement request may include the identifier (the entitlement card number).	EM12006	Card Number must be known to Te Whatu Ora	The PSC Card Number must be known to Te Whatu Ora	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 Patient can have a maximum of twelve active PSC Entitlements	EM12002	Active entitlement limit	The patient cannot have more than twelve active PSC Entitlements	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	400 Bad request
PSC Payor must be set to Te Whatu Ora (Org ID - G0K357-H)	EM12029	Invalid Payor	Invalid Payor	400 Bad request
Coverage period date must be a full date	EM12030	Coverage period date must be a full date	Coverage period date must be a full date	400 Bad request