New Zealand NES IG
1.4.6 - Release

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

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)

Scenarios

  • CSC
    • The CSC details returned from the entitlement service are different from the information on the CSC card the person presents with.
    • A CSC entitlement needs to be ended as it has been entered in error.
  • PSC
    • The PSC details returned from the entitlement service are incorrect and need updating.
    • The pharmaceutical subsidy card needs to be ended as it has been entered in error.
Update EntitlementIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> NES Entitlement<FHIR API> NES EntitlementDBDBProvide details to update apersons entitlementPUT[base]/Coverage/[entitlement-id]Validate[]UpdateHTTP 200 - EntitlementUpdatedDisplay updatedentitlement details

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 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
  • Is a required field
  • EntitlementID is a required field
  • 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 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
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
PSC start date must not be a future date
  • EM07212
  • Cannot be a future 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
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