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

General

The following notes apply to all resources in this implementation.

Resource representation: Json

Only Json is supported by this implementation.

Id and Identifiers

All of the FHIR resources in this implementation have both an id and an identifier.

The id is the ‘physical’ identity of the resource, and the identifier is the business identifier.

In this implementation, the id of the resource will always be the same as the value of the identifier assigned by the HPI with a use value of ‘official’. (There will only ever be a single identifier with this use type and system in a resource). Thus the id for the resource below would be ‘92ZZRR’, and the url something like:

https://api.hip.digital.health.nz/fhir/Practitioner/92ZZRR

This design allows an implementer to retrieve a resource from the HPI and save it on their own system, but still be able to retrieve the original to check for updates. This can be done in 2 ways.

Read resource by id

Extract the value of the identifier where the value of the use element is ‘official’, and use that as the id for a direct read from the server.

Example:

Get/Resource/identifier

Get<Endpoint>/Practitioner/92ZZRR
Get<Endpoint>/Organization/GZZ999-J

For more information look at the _Get Use cases_ in the 'Use cases' menu

Query resource

Use an identifier (medical-council-id) in a search query

Each resource has more than one identifier. If a user wants to query the HPI using another identifier, both the system and identifier needs to be provided

Example:

• Practitioner:
  • medical-council-id
    • System - https://standards.digital.health.nz/ns/medical-council-id
    • Identifier - 99536
  • nursing-council-id
    • System - https://standards.digital.health.nz/ns/nursing-council-id
    • Identifier - 961049
• Organization
  • legacyOrgId
    • System - https://standards.digital.health.nz/ns/nzhis-agency-id
    • Identifier - 9000
  • nzbn
    • System - https://standards.digital.health.nz/ns/hpi-nzbn
    • Identifier - 9999999999001
• Location
  • legacyFacId
    • System - https://standards.digital.health.nz/ns/nzhis-facility-id
    • Identifier - Z995

Note: Both system and value are included in the query, with values separated by a ‘|’. When making the query, the ‘|’ needs to be url-escaped)

• Get<Endpoint>/Practitioner?identifier=https://standards.digital.health.nz/ns/medical-council-id|99536
  
• Get<Endpoint>/Organization?identifier=https://standards.digital.health.nz/ns/hpi-nzbn|9999999999057
  
• Get<Endpoint>/Organization?identifier=https://standards.digital.health.nz/ns/nzhis-agency-id|9000
  
• Get<Endpoint>/Location?identifier=https://standards.digital.health.nz/ns/nzhis-facility-id|Z995
  

These examples will return a bundle of resources with only a single entry (as the system enforces uniqueness of the identifier). Other queries - eg name - may well return multiple instances.

For more information look at the Search Use cases in the menu

Additional search parameters

Search resource using a string

• For a simple string search, a string parameter serves as the input for a search against sequences of characters.
• By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value.
• The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched.
• The :exact modifier returns results that match the entire supplied parameter, including casing and accents.

Examples

• Get<Endpoint>/Organization?name=Pharmacy
  • Any organisations with the name "Pharmacy” at the start of the name. E.g. Pharmacy council of New Zealand will be returned in the bundle.
• Get<Endpoint>/Organization?name:contains=Pharmacy
  • Any organisations with a name containing "Pharmacy" at any position. E.g. This would return “Pharmacy council of New Zealand”, as well as “shopNSave Discount Pharmacy” among others in the bundle.
• Get<Endpoint>/Organization?name:exact=Pharmacy
  • Any organisations with a name that is exactly "Pharmacy". Note: This would not return any of the above examples. However if this was Get<Endpoint>/Organization?name:exact=shopNSave Discount Pharmacy it would return a bundle with that resource.

Count and Offset

The HPI APIs default to returning 10 results on a search request. To receive more than 10, and for pagenated searching follow the pattern described below.

• Facility
  • Search for all facilites of a given type
  • Search for all facilities in a given DHB
• Organisation
  • Search for all organisations of a given type.

A search defaults to return 10 records in the search bundle E.g. GET<Endpoint>/Location?type=pharm will return the first 10 HPI facilites of type pharm.

To increase the number of results returned, and to get all facilities returned there are two parameters to include _count and _offset.

• _count - This search parameter is used to extend the search and has a limit of 50 search results.
• _offset - This search parameter is used to get the next set of search results

E.g. For how to use these parameters

• First request - GET<Endpoint>/Location?type=pharm&_count=50
• Second request - GET\/Location?type=pharm&_count=50&_offset=50
• Third request - GET\/Location?type=pharm&_count=50&_offset=100

References between resources

References are directional - from a source to a target.

The following example shows a reference to a Practitioner with the id of "92ZZRR"

`` "practitioner": { "reference": "Practitioner/92ZZRR", "display": "Dr Marcus welby" } …

Merging resource and Dormant identifiers

In some cases, a single entity may have been accidentally assigned multiple identifiers. When this is discovered to have occurred, one of the identifiers is deprecated and becomes a ‘dormant’ identifier, leaving the other as the active one. Both identifiers will appear in the active resource identifier list, with the dormant identifiers having a use value of ‘old’ and the active having a use value of ‘official’.

When reading the resource, if the deprecated id is used, the resource returned will have the live id, but the identifiers will have both the live with a use value of ‘official’ and this dormant with a use value of ‘old’.)

For example, assume that there are 2 Practitioner resources exposed by the HPI, each with a single identifier. The id of the resource matches the identifier value.

{
  "resourceType":"Practitioner",
  "id" : "92ZZRR",
  "identifier" : [
        {"system":"https://standards.digital.health.nz/id/hpi-person","value":"92ZZRR","use":"official"}


  ]
… other data
}

(returned by GET<Endpoint>/Practitioner/92ZZRR)

And

{
  "resourceType":"Practitioner",
  "id" : "96YYY",
  "identifier" : [
        {"system":"https://standards.digital.health.nz/id/hpi-person","value":"96YYY","use":"official"}


  ]… other data (may be different to 92ZZRR)

}

(returned by GET<Endpoint>/Practitioner/96YYY)

They are determined to be the same person, and the identifier 96YYY is deprecated (made dormant) in favour of 92ZZRR.

A Get call on <Endpoint>/Practitioner/92ZZRR or <Endpoint>/Practitioner/96YYYY will return the same response

{
  "resourceType":"Practitioner",
  "id" : "92ZZRR",
  "identifier" : [
        {"system":"https://standards.digital.health.nz/id/hpi-person","value":"92ZZRR","use":"official"},
        {"system":"https://standards.digital.health.nz/id/hpi-person","value":"96YYYY","use":"old"}


  ]
… other data

}

Resources that reference the Practitioner (such as the PractitionerRole resource) can use either id. For example, to return PractitionerRole resources for this Practitioner, either of the following queries will return the same set of PractitionerRole resources:

GET<Endpoint>/PractitionerRole?practitioner=92ZZRR

GET<Endpoint>/PractitionerRole?practitioner=96YYYY

Contained resources

Contained resources are where the referenced (target) resource is contained within the source resource.

When a resource contains a reference to another resource, the HPI server will not normally render the references as a contained resource, only the reference links themselves will be included in responses. The exception is PractitionerRole, here the server may return contained resources if requested to. This is an example of a request made for the referenced resources to be included

GET<Endpoint>/PractitionerRole?practitioner=99ZZZZ&_include=PractitionerRole:practitioner&_include=PractitionerRole:organization&_include=PractitionerRole:location`

Errors

HTTP Error response codes

Error Format

Error responses may contain a FHIR operation outcome: We’re transitioning to the following operation outcome

{
  "resourceType": "OperationOutcome",
  "issue": [ {
    "severity": "error",
    "code": "processing",
    "details": {
      "coding": [ {
        "system": "https://standards.digital.health.nz/ns/hip-operation-outcome-details-code",
        "code": "EM07106",
        "display": "Record version provided is out of date. The record cannot be updated"
      } ]
    },
    "expression": [ "Practitioner.identifier:HPI" ]
  } ]
}

But not all errors have been converted or assigned error codes, the unconverted errors use:

{
  "resourceType": "OperationOutcome",
  "issue": [ {
    "severity": "error",
    "code": "processing",
    "diagnostics": "Authentication: missing userid header"
  }

Request Rules and Errors

• Request rules
  • Every request must include an:
    • http header item UserId that uniquely identifies the individual initiating the request.
    • OAuth 2 access token
    • An api-key
  • Each user must have an individual userID
• Request errors
  • "Authentication: missing userid header (HTTP 401, Error, Processing)
  • "Unauthorized" (HTTP 401)
  • Forbidden, HTTP403

HTTP Header Details

• This list is any additions to standard HTTP header protocol

Request Headers

Response Headers

Security

OAUTH2

The HPI server uses the OAUTH2 Client Credentials flow for authentication and authorisation and complies with the SMART specification for backend services

Scopes

The following scopes are supported. For more information on available functionality please see Business Functions.

API Keys and Usage Plans

Clients will be emailed their API key, which should be treated as confidential information and not shared with other parties.

An api-key associates the client with a usage plan, which sets upper limits on the API request volume which is permitted. If a client exceeds their usage plan allocation an http error will be returned.

Clients will need to add there api key to the x-api-key header in each API request. If no API key is included in the request header, a “Forbidden” error will be returned

Usage Plans

All test accounts will be assigned to the bronze usage plan

​Production accounts will be assigned to the silver usage plan. If an Organisation wished to be assigned to the gold usage plan, they should contact the Te Whatu Ora HPI access team

If an application reaches its usage plan limit an HTTP 429 error will be returned. The expected behaviour is that the application will retry several times with an exponentially increasing delay

GEO Restriction

GEO Restriction rules prevent access from clients with IPs located in countries other than those listed below. If you need access from another country, please contact our team by completing the Enquiry form or adding a comment to the online onboarding request form if you have one.

• New Zealand
• Australia
• Canada
• Cook Islands