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

Update Entitlement

Update Entitlement Overview

This operation is used to update a patient's entitlement for subsidised healthcare. It is used when the entitlement reurned from the service is showing incorrect information, or if there is a need to end the entitlement.

This operation is used to update a:

• Community services card emtitlement (CSC)
• Pharmaceutical subsidy card entitlement (PSC)

Additional information

CSC

• The update CSC operation should be used when:
  • The CSC details returned from the entitlement service are different from the information on the CSC the person presents with. In the update operation the new card number will be provided. The current entitlement.id (coverage.id) will be maintained, however the entitlement will be updated to present the new details as shown on the card provided by MSD.
  • A CSC entitlement needs to be ended as it has been entered in error. The card should be end dated with status 'entered-in-error'.

PSC

• The update PSC operation should be used when:
  • The PSC details returned from the entitlement service are incorrect and need updating.
  • The PSC entitlement needs to be ended as it has been entered in error. The card should be end dated with status 'entered-in-error'.

Update Entitlement processing steps:

1. The user inputs details required to update or end the entitlement.
2. The integrating application sends a PUT request to the NES Coverage endpoint with a payload containing the NesEntitlement resource to be updated.
3. The request is validated - ALT: Validation failure. Operation Outcome resource returned
4. The Entitlement is updated in the database.
5. The updated Entitlement is returned to the client, or the Entitlement is ended.

Update Entitlement Request Example

update CSC Entitlement example requests

update PSC Entitlement example requests

Update Entitlement Rules and Errors

Update community services card entitlement rules and errors

For Request rules and errors click here

Rule	Error code	Error description	Error text	Http code
An update CSC entitlement request must include:: A valid Entitlement ID Entitlement type beneficiary (NHI number of the patient) identifier (the entitlement card number) contained Patient resource organisation approving the entitlement (payor) status Period end (if ending the entitlement)	EM07201	Is a required field	EntitlementID is a required field li>Entitlement type is a required field</li> 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 and validate with the National Health Index	EM02008	The patient identity information supplied does not match the patient identity information in the NHI.	The patient identity information supplied does not match the patient identity information in the NHI.	400 Bad request
The NHI provided must match the NHI associated with the Entitlement.	TBC	The requested NHI is not consistent with the Entitlement.	The requested NHI is not consistent with the Entitlement.	400 Bad request
A request to update 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	400 Bad request
An update CSC entitlement request must include a valid CSC Card Number.	EM12006	The CSC Card Number must be known to MoH	The CSC Card Number must be known to MoH	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
An update to end entitlement must match current entitlement and include end period and status ‘entered in error’	EM12026 EM12027	Invalid termination reason (status) Update to end must match previous entitlement	Invalid termination reason (status) Update to end must match previous entitlement	400 Bad request

Update pharmaceutical subsidy cards entitlement rules and errors

For Request rules and errors click here

Rule	Error code	Error description	Error text	Http code
An update PSC entitlement request must include: EntitlementID type of entitlement beneficiary (NHI number of the patient) identifier (the entitlement card number) contained Patient resource organisation approving the entitlement (payor) status period - start period end (if ending the entitlement)	EM07201 EM12020 EM12021	Is a required field entitlement-id supplied cannot be found Supplied entitlement-id is invalid	EntitlementID is a required field entitlement-id supplied cannot be found Supplied entitlement-id is invalid entitlement type is a required field contained Patient is required beneficiary is a required field identifier is a required field status is a required field payor is a required field period start is a required field	400 Bad request
The entitlement must be active to be updated	EM12028	The requested entitlement is not active	The requested entitlement is not active	400 Bad request
The contained patient must match Entitlement beneficiary and validate with the National Health Index	EM02008	The patient identity information supplied does not match the patient identity information in the NHI.	The patient identity information supplied does not match the patient identity information in the NHI.	400 Bad request
The NHI provided must match the NHI associated with the Entitlement.	EM12018	The requested NHI is not consistent with the Entitlement.	The requested NHI is not consistent with the Entitlement.	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
Cannot update entitlement for deceased person	EM12022	Cannot create or update entitlement for deceased person	Cannot create or update entitlement for deceased person	400 Bad request
A request to update 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	400 Bad request
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 end date must be greater than, or equal to start date, and not a future date	EM12024 EM12025	End date cannot be before start date End date cannot be in the future	End date cannot be before start date End date cannot be in the future	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
An update to end entitlement must match current entitlement and include end period and status ‘entered in error’	EM12026 EM12027	Invalid termination reason (status) Update to end must match previous entitlement	Invalid termination reason (status) Update to end must match previous entitlement	400 Bad request