New Zealand HPI Implementation Guide
1.5.0 - Release

New Zealand HPI Implementation Guide, published by Te Whatu Ora. This guide is not an authorized publication; it is the continuous build for version 1.5.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7NZ/hpi/ and changes regularly. See the Directory of published versions

Get Organisation

Get Organisation Overview

The Get Organisation use case describes how a user can access an HPI organisation record from the HPI.

Get Organisation using hpi-organisation-id

Get Organization by hpi-organisation-id sequence diagramIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> HPI<FHIR API> HPIHPI MDMHPI MDMLook up organization withhpi-organisation-idGET<Endpoint>/Organization/[hpi-organisation-id]Validate[]RequestReturn organization recordDisplay Organization details

Get Organisation processing steps:

  1. The user supplies a hpi-organisation-id for the Organisation to be looked up
  2. The integrating application sends an HTTP GET request for the Organization resource using the hpi-organisation-id to identify the Organisation whose information is being requested E.g. GET<Endpoint>/Organization/GZZ999-J
  3. The request is validated - ALT: Validation failure. Operation Outcome resource returned
  4. The Organization resource is retrieved from the HPI - ALT: Organization not found. Operation Outcome resource returned
  5. The response containing the Organization resource is returned
  6. The Organisation details are provided to the user

Get organisation rules and errors

For Request rules and errors click here
Rule Error code Error description Error text / expression Http code
An organisation read request must include a valid hpi-organisation-id
  • Invalid ID: <>
  • 404 Not found

Query Organisation with 'other identifier'

To query an Organisation with an ‘other identifier' the integrating application sends an HTTP GET request for the Organisation resource using the ‘other identifier’ and the identifier system.

The 'other identifier's that may be requested include

  • The Legacy agency code (NZHIS)
    • using the url GET<Endpoint>/Organization?identifier=https://standards.digital.health.nz/ns/nzhis-agency-id|9000
  • The New Zealand Business Number (NZBN)
    • using the url GET<Endpoint>/Organization?identifier=https://standards.digital.health.nz/ns/hpi-nzbn|9999999999001

Query Organisation using other identifier - NZ Business number (NZBN)

For more information on read vs query click here

Query Organisation using NZBN identifier sequence diagramIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> HPI<FHIR API> HPIHPI MDMHPI MDMUser enters NZBN andidentifier systemGET<Endpoint>/Organization?identifier=[system]|[identifier]Validate[]Get[Organisation]Return Bundle containingthe Organisation recordDisplay Organisation detailsto user

Query organisation using other identifier processing steps (E.g. NZBN)

  1. The user supplies the system (https://standards.digital.health.nz/ns/hpi-nzbn) and identifier (NZBN) for the organisation.
  2. The integrating application sends an HTTP Get request for the organization resource using the NZBN to identify the organisation whose information is being requested. E.g. GET<Endpoint>/Organization?identifier=https://standards.digital.health.nz/ns/hpi-nzbn|9999999999001
  3. The request is validated - ALT: Validation failure. OperationOutcome resource returned
  4. The Organization resource is retrieved from the HPI - ALT: Organization reource not found. OperationOutcome resource returned
  5. The response containing a bundle with a single Organisation record is returned
  6. The integrating application displays the Organisation details to the user

Query organisation rules and errors

For Request rules and errors click here
Rule Error code Error description Error text / expression Http code
A query organisation request must include a valid 'other identifer' and the identifier system
  • EM01100
  • System error occured while processing the request
  • Unknown identifier system: \<>
  • Organization.identifier:nzbn
  • 422 Unknown
  • 422 Unknown