New Zealand HPI Implementation Guide
1.5.0 - Release

New Zealand HPI Implementation Guide - Local Development build (v1.5.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Get Facility

Get Facility Overview

The Get Facility use case describes how a user can find an HPI facility record. HPI Facilities are returned using the HL7 FHIR Location resource.

Get facility using an hpi-facility-id

Get Facility sequence diagramIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> HPI<FHIR API> HPIHPI MDMHPI MDMLook up facility withhpi-facility-idGET<Endpoint>/Location/[hpi-facility-id]Validate[]RequestReturn Location recordDisplay Facility (Location)details

Get facility (Location) processing steps:

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

Get Facility rules and errors

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

Query Facility using the Location the NZHIS (Legacy) identifier

To query a Facility with the NZHIS (Legacy) identifier, the integrating application sends an HTTP Get request for the Location resource using the NZHIS (Legacy) identifier and the identifier system.

For more information on read vs query click here

Query Facility using NZHIS (Legacy) identifier sequence diagramIntegrating application userIntegrating application userIntegrating applicationIntegrating application<FHIR API> HPI<FHIR API> HPIHPI MDMHPI MDMUser enters NZHIS (Legacy)identifier and identifiersystemGET<Endpoint>/Location?identifier=[system]|[identifier]Validate[]Get[Location]Return Bundle containingthe Facility recordDisplay Facility details touser

Query facility (location) processing steps

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

Query Facility rules and errors

For Request rules and errors click here
Rule Error code Error description Error text / expression Http code
A Facility query request must include a valid registration authority identifier and 'system'
  • EM07240
  • Unknown identifier system: https://standards.digital.health.nz/ns/nzhis-facility-id
  • Resource not found
  • Location.identifier:legacyFacId
  • 422 Unknown
  • 404 Not found