New Zealand NHI IG
1.5.4 - Release

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

Update Address

Update Address Overview

The update address operations allow an authorised user to update a persons address on a persons identity record

Update address has three sub-operations available:

  • Set-address - Allows a user to replace a physical address OR add or replace a postal address with an eSAM validated address
  • Set-unvalidated-address - Allows a user to replace a physical or add or replace a postal address with an unvalidated address
  • Remove-postal-address - Allows a user to remove a postal adddress from a persons identity record.

Set-address

  • Allows a user to replace a physical address OR add or replace a postal address with an eSAM validated address
$set-addressIntegrating application userIntegrating application userIntegrating applicationIntegrating applicationAddress valiation serviceAddress valiation service<FHIR API> NHI<FHIR API> NHINHI MDMNHI MDMProvide patient addressGet addressReturn validated addressPOST<Endpoint>/Patient/$set-addressValidate[]RequestReturn updated PatientrecordDisplay updated Patientrecord to user

Set-address - Processing steps:

  1. The user provides details for a new address to add
  2. The system requests address validation from the address validation service
  3. eSAM returns a validated address - Alt: Address not found
  4. The integrating application sends an HTTP Post request using the $set-address operation to the NHI E.g. Post<Endpoint>/Patient/$set-address
  5. The request is validated - ALT: Validation failure. Operation Outcome resource returned
  6. The new address is added to the NHI and the existing address made inactive
  7. The updated patient record is returned with an HTTP 200 ok response
  8. The integrating application displays the updated patient details to the user

Set-address - 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
address-type valueString Mandatory postal or physical
nz-address-id valueString Mandatory eSAM validated address id
address-line valueString Mandatory first line of the address as returned by eSAM
address-building-name valueString Optional The building name, this is additional information and is not returned as part of the eSAM address

Set-address - Behaviour

  • The NHI is validated
  • The Patient version-id is validated
  • The parameters are validated
  • The eSAM details are retrieved for the nz-address-id supplied
  • If the eSAM address returned matches the address-line supplied, the new address is added to the NHI and the existing address made inactive

Set-address - Example request

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
        "name" : "nhi",
        "valueString" : "ZGD9203"
    },
    {
        "name" : "version-id",
        "valueString" : "3321540"
    },
     {
        "name" : "address-type",
        "valueString" : "physical"
    },
    {
        "name" : "nz-address-id",
        "valueString" : "2843216"
    },
    {
        "name" : "address-line",
        "valueString" : "20 Aitken Street"
    },
        {
        "name" : "address-building-name",
        "valueString" : "Freyberg House"
    }
  ]
}

Set-address - Rules and errors

For Request rules and errors click here

Patient set-address rules
  • All create patient address rules apply, and
  • A Patient Update request must contain the live NHI number for the Patient Record
  • A system must source the most recent Patient Record from the NHI before creating a request to update the Patient record
  • A request must not result in information, removed from a Patient Record by the NHI Administration team being added

  • Patient set-address errors
    • Patient NHI, version number, address type and address-id are all required
    • Version number is incorrect
    • address type must be a postal or physical
    • address-line must match the espatial value: <value>

Set-unvalidated-address

  • Allows a user to replace a physical or add or replace a postal address with an unvalidated address
$set-unvalidated-addressIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> NHI<FHIR API> NHINHI MDMNHI MDMProvide patient addressPOST<Endpoint>/Patient/$set-unvalidated-addressValidate[]RequestReturn updated PatientrecordDisplay updated Patientrecord to user

Set-unvalidated-address - Processing steps:

  1. The user provides details for a new address to add
  2. The integrating application sends an HTTP Post request using the $set-unvalidated-address operation to the NHI E.g. Post<Endpoint>/Patient/$set-unvalidated-address
  3. The request is validated - ALT: Validation failure. Operation Outcome resource returned
  4. The new address is added to the NHI and the existing address made inactive
  5. The updated patient record is returned with an HTTP 200 ok response
  6. The integrating application displays the updated patient details to the user

Set-unvalidated-address - 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
not-validated-address-reason valueString Mandatory
address-type valueString Mandatory postal or physical
address-building-name valueString Optional
address-line-1 valueString Mandatory first line of the address
address-line-2 valueString Optional second line of the address
address-suburb valueString Optional
address-city valueString Optional
address-postal-code valueString Optional
address-country-code valueString Optional
address-domicile-code valueString Optional* See future functionality below

Future functionality for Domicile code

  • If domicile code supplied this is added to the address, if not supplied the suburb and city are used to derive a domicile code from the streets file. If a suburb/city combination is not found in the streets file an error is returned.
  • For now domicile code is currently mandatory.

Set-unvalidated-address - Behaviour

  • The NHI is validated
  • The Patient versionId is validated
  • The parameters are validated
  • With a succcesful address add, the new address is added to the NHI and the existing address made inactive

Set-unvalidated-address - Example request

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
        "name" : "nhi",
        "valueString" : "ZAD2481"
    },
    {
        "name" : "version-id",
        "valueString" : "19232"
    },
     {
        "name" : "not-validated-address-reason",
        "valueString" : "OSEA"
    },
    {
        "name" : "address-type",
        "valueString" : "physical"
    },
    {
        "name" : "address-building-name",
        "valueString" : "Building 11"
    },
    {
        "name" : "address-line-1",
        "valueString" : "67 nowhere street"
    },
    {
        "name" : "address-line-2",
        "valueString" : "nowhere"
    },
 {
        "name" : "address-suburb",
        "valueString" : "darksideodthetracks"
    },
 {
        "name" : "address-city",
        "valueString" : "darkside"
    },
 {
        "name" : "address-postal-code",
        "valueString" : "60606"
    },
     {
        "name" : "address-country-code",
        "valueString" : "NZ"
    }
  ]
}

Set-unvalidated-address - Rules and errors

For Request rules and errors click here

Patient set-unvalidated-address rules
  • All create patient address rules apply, and
  • A Patient Update request must contain the live NHI number for the Patient Record
  • A system must source the most recent Patient Record from the NHI before creating a request to update the Patient record
  • A request must not result in information, removed from a Patient Record by the NHI Administration team being added

  • Patient set-unvalidated-address errors
    • Patient NHI, version number, address type and address-id are all required
    • Version number is incorrect
    • address type must be a postal or physical
    • address-line must match the espatial value: <value>

Remove-postal-address

  • Allows a user to remove a postal adddress from a persons identity record.
$remove-postal-addressIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> NHI<FHIR API> NHINHI MDMNHI MDMRequests postal addressremovalPOST<Endpoint>/Patient/$remove-postal-addressValidate[]RequestReturn updated PatientrecordDisplay updated Patientrecord to user

Remove-postal-address - Processing steps:

  1. The user requests to remove a postal address
  2. The integrating application sends an HTTP Post request using the $remove-postal-address operation to the NHI E.g. Post<Endpoint>/Patient/$remove-postal-address
  3. The request is validated - ALT: Validation failure. Operation Outcome resource returned
  4. The postal address is made inactive
  5. The updated patient record is returned with an HTTP 200 ok response
  6. The integrating application displays the updated patient details to the user

Remove-postal-address - 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

Remove-postal-address - Behaviour

  • The NHI is validated
  • The Patient version-id is validated
  • The postal address on the nhi record is made inactive

Remove-postal-address - Example request

{
  "resourceType": "Parameters",
  "id": "example",
  "parameter": [
    {
        "name" : "nhi",
        "valueString" : "ZAD2481"
    },
    {
        "name" : "version-id",
        "valueString" : "19232"
    }
  ]
}

Remove-postal-address - Rules and errors

For Request rules and errors click here

Patient remove-postal-address rules
  • All create patient address rules apply, and
  • A Patient Update request must contain the live NHI number for the Patient Record
  • A system must source the most recent Patient Record from the NHI before creating a request to update the Patient record

  • Patient remove-postal-address errors
    • Patient NHI, version number, address type and address-id are all required
    • Version number is incorrect