New Zealand HPI Implementation Guide
1.4.4 - Release
New Zealand HPI Implementation Guide - Local Development build (v1.4.4) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
The following notes apply to all resources in this implementation.
Only Json is supported by this implementation.
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.
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 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:
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)
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
Examples
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.
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.
E.g. For how to use these parameters
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” } …
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 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`
| Status code | Description |
|---|---|
| 400 | Bad Request |
| 401 | The client needs to provide credentials, or has provided invalid credentials. |
| 403 | Authentication was provided, but the authenticated user is not permitted to perform the requested operation. |
| 404 | Resource not found |
| 405 | HTTP method not allowed |
| 409 | Resource conflict, the version provided for the resource is not the current version |
| 413 | The request body was too big for the server to accept |
| 422 | Unprocessable Entity, resource was rejected by the server because it “violated applicable FHIR profiles or server business rules” |
| 500 | General system failure |
| 429 | Exceeded quota |
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"
}
| HTTP Header (Key) | HTTP Header (Value) | Description | Mandatory / Recommended / Optional |
|---|---|---|---|
| Authorization | Bearer {string} | The OAuth2 access token | Mandatory |
| userid | {string} | Client provided All requests for all resources must include an http header userid that uniquely identifies the individual initiating the request Preferably the hpi-person-id of the user would be provided if known, otherwise a userid that allows the authenticated organisation to identify the individual |
Mandatory |
| Content-Type | Application/json | Supported content type | Mandatory |
| x-api-key | {string} | Te Whatu Ora Provided – issued with client credentials | Mandatory |
| User-Agent | {string} | The user-agent header is a string field that lets Te Whatu Ora know the application and version of the application accessing the HIP APIs. | Mandatory |
| X-Correlation-Id | {string} | Client provided All requests should contain a unique transaction id in the X-Correlation-Id field If present in the request this will be returned in the response, and can be used to track API calls Preferred less than 64 characters |
Recommended |
| if-Match | {integer} | The version-id of the record to be updated | * Mandatory - PracRole update only * |
| Element name | Value | Description |
|---|---|---|
| X-Correlation-Id | {string} | Returned if provided |
| X-request-Id | {string} | Unique identifier for the request within the NHI |
| ETag | {string} | The resource version number, returned on a Get |
The HPI server uses the OAUTH2 Client Credentials flow for authentication and authorisation and complies with the SMART specification for backend services
The following scopes are supported. For more information on available functionality please see Business Functions.
| SMART on FHIR Scopes | Description |
|---|---|
| https://api.hip.digital.health.nz/fhir/system/Practitioner.r | Read access to all Practitioner resources. Gender, birthDate and ethnicity are not disclosed |
| https://api.hip.digital.health.nz/fhir/system/Practitioner.s | Search access to Practitioner resources Gender, birthDate and ethnicity are not disclosed Practitioners tagged as confidential are excluded from the results |
| https://api.hip.digital.health.nz/fhir/system/Practitioner.u | Allows user to update practitioner records |
| https://api.hip.digital.health.nz/fhir/system/Practitioner.c | Allows user to create practitioner records |
| https://api.hip.digital.health.nz/fhir/system/Practitioner.a | Admin access to all Practitioner resources Allows access to confidential data, gender, birthDate and ethnicity Allows access to merge records |
| https://api.hip.digital.health.nz/fhir/system/Location.r | Read access to all Location resources |
| https://api.hip.digital.health.nz/fhir/system/Location.s | Search access to all Location resources |
| https://api.hip.digital.health.nz/fhir/system/Organization.r | Read access to all Organization resources |
| https://api.hip.digital.health.nz/fhir/system/Organization.s | Search access to all Organization resources |
| https://api.hip.digital.health.nz/fhir/system/PractitionerRole.r | Read access to all Practitioner Role resources |
| https://api.hip.digital.health.nz/fhir/system/PractitionerRole.s | Search access to all active Practitioner Role resources, inactive roles are excluded from the results |
| https://api.hip.digital.health.nz/fhir/system/PractitionerRole.u | Update access to all Practitioner Role resources. |
| https://api.hip.digital.health.nz/fhir/system/PractitionerRole.c | Create access to all Practitioner Role resources. |
| https://api.hip.digital.health.nz/fhir/system/PractitionerRole.a | Admin access to all Practitioner Role resources Allows access to confidential data Allows access to merge records |
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
| Plan | Rate | Burst | Quota |
|---|---|---|---|
| bronze | 1 request per second | 5 | 10,000 requests per day |
| silver | 5 requests per second | 25 | 250,000 requests per day |
| gold | 10 requests per second | 50 | 500,000 requests per day |
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 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.