New Zealand NHI IG
1.6.5 - Release

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

Maintain Contact

Maintain Contact

The maintain contact operations allow an authorised user to maintain a person's contact information on their identity record.

Three operations are available:

  • add-contact – Set the Preferred Name the person wishes to be identied as
  • replace-contact – Add a new name to the set of Patient Names for this NHI record
  • delete-contact – Replace a name that is currently on the patients NHI record

Add-contact Overview

  • Allows an authorised user to add a contact to a patient's NHI record
$add-contact$add-contactIntegrating application<FHIR API> NHINHI MDMIntegrating application userIntegrating application<FHIR API> NHINHI MDMIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> NHI<FHIR API> NHINHI MDMNHI MDMIntegrating application<FHIR API> NHINHI MDMProvide new patientcontact to be added to apatient recordPOST<base-url>/fhir/nhi/v1/Patient/$add-contactValidate[]RequestReturn updated PatientrecordDisplay updated patientdetails to user

Add-contact - Processing steps:

  1. The user provides the new contact details to be added to the patient's NHI record
  2. The integrating application sends an HTTP Post request using the $add-contact operation to the NHI E.g.Post <Endpoint>/Patient/$add-contact
  3. The request is validated - ALT: Validation failure. Operation Outcome resource returned.
  4. The updated patient record is returned with an HTTP 200 ok response.
  5. The integrating application displays the updated patient details to the user.

Add-contact - In Parameters

Parameter name Parameter type Mandatory / Optional Description
nhi valueString Mandatory The patient's nhi number
version-id valueString Mandatory The current patient version number
use valueString Optional home or mobile
system valueString Optional phone or email
value valueString Optional the phone number or email address
isVerified valueString Optional Verification has been performed to determine that the email or phone number can be used to communicate with the patient (true or false)
isShared valueString Optional The email address or phone number is shared with other people (true or false)
isPrivate valueString Optional The email address or phone number may be used to communicate private health information about the individual identified by the NHI

Add-contact - Behaviour

  • The NHI is validated.
  • The Patient version-id is validated.
  • The contact details are validated.
  • If all request parameters are valid the name.preferred boolean is set to TRUE on the requested name and FALSE on the current preferred name.

Add-contact - Example request

add-contact request

Add-contact - Rules and errors

For Request rules and errors click here

Add-contact rules
* Add-contact request must contain: 
* the live NHI number for the Patient Record.
* the version number of the current Patient Record.
* the contact details
  • Add-contact errors.
  • A valid NHI, preferred ID and version number are required.

Replace-contact Overview

  • Allows an authorised user to replace patient contact details for this NHI record.
$replace-contact$replace-contactIntegrating application<FHIR API> NHINHI MDMIntegrating application userIntegrating application<FHIR API> NHINHI MDMIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> NHI<FHIR API> NHINHI MDMNHI MDMIntegrating application<FHIR API> NHINHI MDMProvide the id of thecontact to be replaced andthe details of the contactto replace it withPOST<base-url>/fhir/nhi/v1/Patient/$replace-contactValidate[]RequestReturn updated PatientrecordDisplay updated patientdetails to user

Replace-contact - Processing steps:

  1. The user provides the new patient contact to be added to the patients NHI record, and the id of the existing contact which is to be replaced.
  2. The integrating application sends an HTTP Post request using the $add-name operation to the NHI E.g. Post <Endpoint>/Patient/$replace-contact
  3. The request is validated - ALT: Validation failure. Operation Outcome resource returned.
  4. The updated patient record is returned with an HTTP 200 ok response.
  5. The integrating application displays the updated patient details to the user.

Replace-contact - In Parameters

Parameter name Parameter type Mandatory / Optional Description
nhi valueString Mandatory The patients nhi number
version-id valueString Mandatory The current patient version number
contact-id valueString Mandatory The id of the contact element to be replaced
use,system,value,isVerified,isShared ​ as per Add-contact - In Parameters

Replace-contact - Behaviour

  • The NHI is validated.
  • The Patient version-id is validated.
  • If all request parameters are valid the old contact is replaced by the new contact.

Replace-contact- Example request

​replace-contact request

Replace-contact - Rules and errors

For Request rules and errors click here

Replace-contact rules
  • ​All add-contact rules apply, and
  • An replace-contact request must contain:
    • the live NHI number for the Patient Record.
    • the version number of the current Patient Record.
  • Replace Contact errors.
    • Patient NHI and version number are required.
    • Version number is incorrect.
    • The contact-id does not exists for this patient.

Delete-contact Overview

  • Allows an authorised user to delete a patient's contact from the NHI record.
$delete-contact$delete-contactIntegrating application<FHIR API> NHINHI MDMIntegrating application userIntegrating application<FHIR API> NHINHI MDMIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> NHI<FHIR API> NHINHI MDMNHI MDMIntegrating application<FHIR API> NHINHI MDMProvide the id of thecontact to be deleted fromthe patient recordPOST<base-url>/fhir/nhi/v1/Patient/$delete-contactValidate[]RequestReturn updated PatientrecordDisplay updated patientdetails to user

Delete-contact - Processing steps:

  1. The user provides the id of the contact to be deleted from the NHI E.g. Post<Endpoint>/Patient/$delete-contact.
  2. The request is validated - ALT: Validation failure. Operation Outcome resource returned.
  3. The updated patient record is returned with an HTTP 200 ok response.
  4. The integrating application displays the updated patient details to the user.

Delete-contact - In Parameters

Parameter name Parameter type Mandatory / Optional Description
nhi valueString Mandatory The patients nhi number
version-id valueString Mandatory The current patient version number
contact-id valueInteger Mandatory The id of the contact to be deleted

Delete-contact - Behaviour

  • The NHI is validated.
  • The Patient version-id is validated.
  • The contact-id is validated.
  • If all request parameters are valid the contact identified in the request will be deleted from the NHI.

Delete-contact - Example request

delete-contact request

Delete-contact - Rules and errors

For Request rules and errors click here

Delete-contact rules
  • An delete-contact request must contain:
    • the live NHI number for the Patient Record.
    • the version number of the current Patient Record.
    • the contact-id of the contact to be deleted
  • Delete contact errors.
    • Patient NHI and version number are required.
    • Version number is incorrect.
    • The contact-id does not exists for this patient.