NZ Shared Digital Health Record API

NZ Shared Digital Health Record API - Local Development build (v0.5.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

CapabilityStatement: NZ Shared Digital Health Record API

Official URL: https://fhir-ig.digital.health.nz/sdhr/CapabilityStatement/SDHRCapabliityStatement				Version: 0.5.0
Draft as of 2024-04-15				Computable Name: SDHRCapabliityStatement

Raw OpenAPI-Swagger Definition file | Download

Profile: Capability Statement profile for use with the Health New Zealand Te Whatu Ora OpenAPI spec converter

Implementation Guide Version: 0.5.0
FHIR Version: 4.0.1
Supported Formats: application/fhir+json
Supported Patch Formats:
Published on: 2024-04-15 01:15:23+0000
Published by: Health New Zealand

Note to Implementers: FHIR Capabilities
Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.

FHIR RESTful Capabilities

Mode: `server`

Request-Context custom header

All FHIR API requests MUST include the HNZ request context custom header which supplies identifiers for the health user and organisation, or system behind the API request.

This context is supplied using the 'Request-Context' custom HTTP header in the form of a base64-encoded JSON object. The value of the header has differing forms based on the type of request being made, namely whether it is in a user context (e.g. a clinical user searching for patient records), or a system context (e.g. a system submitting data to the API in a bulk load scenario).

Requests with user context

Context property Mandatory Value

userIdentifier Yes The userid of the user as authenticated by the PMS/health application

secondaryIdentifier Yes The secondary identifier for the user - this MUST be the end users Common Person Number (aka HPI Practitioner identifier) of the practitioner using the application where available. Otherwise, any secondary identifier that is held for the user

purposeOfUse Yes One of [ "PATRQT", "POPHLTH", "TREAT", "ETREAT", "PUBHLTH", "SYSDEV" ]. For descriptions of the values, see Audit Events

userFullName Yes Full name of the user of the PMS/health application.

userRole Yes Role of the user of the PMS/health application. Set to "PROV" (Provider) or "PAT" (Patient)

orgIdentifier No (preferred) The HPI Organisation Number (aka HPI Organisation identifier) for the organisation in which the API consumer application is deployed

facilityIdentifier No (preferred) HPI identifier for the facility where the user is located

Context property	Mandatory	Value
`userIdentifier`	Yes	The userid of the user as authenticated by the PMS/health application
`secondaryIdentifier`	Yes	The secondary identifier for the user - this MUST be the end users Common Person Number (aka HPI Practitioner identifier) of the practitioner using the application where available. Otherwise, any secondary identifier that is held for the user
`purposeOfUse`	Yes	One of [ "PATRQT", "POPHLTH", "TREAT", "ETREAT", "PUBHLTH", "SYSDEV" ]. For descriptions of the values, see Audit Events
`userFullName`	Yes	Full name of the user of the PMS/health application.
`userRole`	Yes	Role of the user of the PMS/health application. Set to `"PROV"` (Provider) or `"PAT"` (Patient)
`orgIdentifier`	No (preferred)	The HPI Organisation Number (aka HPI Organisation identifier) for the organisation in which the API consumer application is deployed
`facilityIdentifier`	No (preferred)	HPI identifier for the facility where the user is located

Requests with system context

Context property Mandatory Value

userIdentifier Yes The oAuth clientId of the system submitting data to the API

purposeOfUse Yes [ "SYSDEV" ]. For descriptions of the values, see Audit Events

userFullName Yes Name of the PMS/health application.

userRole Yes Role of the PMS/health application. Set to "110150" (Application)

Context property	Mandatory	Value
`userIdentifier`	Yes	The oAuth clientId of the system submitting data to the API
`purposeOfUse`	Yes	[ "SYSDEV" ]. For descriptions of the values, see Audit Events
`userFullName`	Yes	Name of the PMS/health application.
`userRole`	Yes	Role of the PMS/health application. Set to `"110150"` (Application)

A schema definition and examples for Request-Context can be found here

Example Request-Context Header Payload for a clinical user searching for a patient's Conditions

Base64 Encoded

ewogICJ1c2VySWRlbnRpZmllciI6ICJwbXMtaWQtMTIzIiwKICAidXNlclJvbGUiOiAiUFJPViIsCiAgInNlY29uZGFyeUlkZW50aWZpZXIiOiB7CiAgICAidXNlIjogIm9mZmljaWFsIiwKICAgICJzeXN0ZW0iOiAiaHR0cHM6Ly9zdGFuZGFyZHMuZGlnaXRhbC5oZWFsdGgubnovbnMvaHBpLXBlcnNvbi1pZCIsCiAgICAidmFsdWUiOiAiOTlaWlpTIgogIH0sCiAgInB1cnBvc2VPZlVzZSI6IFsKICAgICJQT1BITFRIIgogIF0sCiAgInVzZXJGdWxsTmFtZSI6ICJCZXZlcmx5IENydXNoZXIiLAogICJvcmdJZGVudGlmaWVyIjogIkcwMDAwMS1HIiwKICAiZmFjaWxpdHlJZGVudGlmaWVyIjogIkZaWjk5OS1CIgp9

Decoded JSON

{
  "userIdentifier": "pms-id-123",
  "userRole": "PROV",
  "secondaryIdentifier": {
    "use": "official",
    "system": "https://standards.digital.health.nz/ns/hpi-person-id",
    "value": "99ZZZS"
  },
  "purposeOfUse": [
    "POPHLTH"
  ],
  "userFullName": "Beverly Crusher",
  "orgIdentifier": "G00001-G",
  "facilityIdentifier": "FZZ999-B"
}

Example Request-Context Header Payload for a system submitting data to the API, where there is no end user

Base64 Encoded

ICB7CiAgICAidXNlcklkZW50aWZpZXIiOiAiMWI4MjAwZDctM2E4Yy00ZmI2LThlNWMtY2VjNDU0MDk5OWQ1IiwKICAgICJ1c2VyUm9sZSI6ICIxMTAxNTAiLAogICAgInB1cnBvc2VPZlVzZSI6IFsKICAgICAgIlNZU0RFViIKICAgIF0sCiAgICAidXNlckZ1bGxOYW1lIjogIlNhbXBsZSBQTVMgSW50ZWdyYXRpb24gQXBwbGljYXRpb24iCiAgfQ==

Decoded JSON

{
  "userIdentifier": "1b8200d7-3a8c-4fb6-8e5c-cec4540999d5",
  "userRole": "110150",
  "purposeOfUse": [
    "SYSDEV"
  ],
  "userFullName": "Sample PMS Integration Application"
}

Mandatory search parameters

All FHIR API search requests must include the HNZ mandatory search parameters. These are listed in the Combined Search Parameters section of each resource below.

Error status codes

Read (GET) Operation Statuses

Code Meaning Description

200 OK The request was successful, and the response body contains the representation requested

302 FOUND A common redirect response; you can GET the representation at the URI in the Location response header

304 NOT MODIFIED Your client's cached version of the representation is still up to date

400 BAD REQUEST Missing or bad Request-Context custom header; FHIR request payload does not validate against Implementation Guide

401 UNAUTHORIZED The supplied credentials, if any, are not sufficient to access the resource

403 FORBIDDEN Insufficient privilege to access the requested FHIR resource/operation

404 NOT FOUND The requested representation was not found. Retrying this request is unlikely to be successful

429 TOO MANY REQUESTS Your application is sending too many simultaneous requests

500 SERVER ERROR An internal server error prevented return of the representation response

503 SERVICE UNAVAILABLE We are temporarily unable to return the representation. Please wait and try again later

Code	Meaning	Description
200	OK	The request was successful, and the response body contains the representation requested
302	FOUND	A common redirect response; you can GET the representation at the URI in the Location response header
304	NOT MODIFIED	Your client's cached version of the representation is still up to date
400	BAD REQUEST	Missing or bad `Request-Context` custom header; FHIR request payload does not validate against Implementation Guide
401	UNAUTHORIZED	The supplied credentials, if any, are not sufficient to access the resource
403	FORBIDDEN	Insufficient privilege to access the requested FHIR resource/operation
404	NOT FOUND	The requested representation was not found. Retrying this request is unlikely to be successful
429	TOO MANY REQUESTS	Your application is sending too many simultaneous requests
500	SERVER ERROR	An internal server error prevented return of the representation response
503	SERVICE UNAVAILABLE	We are temporarily unable to return the representation. Please wait and try again later

Search (GET) Operation Statuses

Code Meaning OperationOutcome in response? Description

200 OK Yes, When there are additional messages about a match result The request was successful, and the response body contains the representation requested

302 FOUND No A common redirect response; you can GET the representation at the URI in the Location response header

400 BAD REQUEST Yes Missing or bad Request-Context custom header;<br>FHIR request payload does not validate against Implementation Guide

401 UNAUTHORIZED Yes The supplied credentials, if any, are not sufficient to access the resource

403 FORBIDDEN Yes Insufficient privilege to access the requested FHIR resource/operation. See OperationOutcome-APIError-Unauthorised

429 TOO MANY REQUESTS No Your application is sending too many simultaneous requests

500 SERVER ERROR No An internal server error prevented return of the representation response

503 SERVICE UNAVAILABLE No The server is temporarily unable to return the representation. Please wait and try again later

Code	Meaning	OperationOutcome in response?	Description
200	OK	Yes, When there are additional messages about a match result	The request was successful, and the response body contains the representation requested
302	FOUND	No	A common redirect response; you can GET the representation at the URI in the Location response header
400	BAD REQUEST	Yes	Missing or bad `Request-Context` custom header;<br>FHIR request payload does not validate against Implementation Guide
401	UNAUTHORIZED	Yes	The supplied credentials, if any, are not sufficient to access the resource
403	FORBIDDEN	Yes	Insufficient privilege to access the requested FHIR resource/operation. See OperationOutcome-APIError-Unauthorised
429	TOO MANY REQUESTS	No	Your application is sending too many simultaneous requests
500	SERVER ERROR	No	An internal server error prevented return of the representation response
503	SERVICE UNAVAILABLE	No	The server is temporarily unable to return the representation. Please wait and try again later

Non existent API endpoints

When a consumer attempts to call a non-existent API end point, respond with a 501 Not Implemented status code.

Security

Enable CORS: yes

Security services supported: SMART-on-FHIR

OAuth 2.0 - Client Credential flow.

Summary of System-wide Interactions

Supports the search-systeminteraction.
Supports the transactioninteraction.
Supports the batchinteraction.

Capabilities by Resource/Profile

Summary

The summary table lists the resources that are part of this configuration, and for each resource it lists:

The relevant profiles (if any)
The interactions supported by each resource (Read, Search, Update, and Create, are always shown, while VRead, Patch, Delete, History on Instance, or History on Type are only present if at least one of the resources has support for them.
The required, recommended, and some optional search parameters (if any).
The linked resources enabled for _include
The other resources enabled for _revinclude
The operations on the resource (if any)

Resource Type	Profile	R	S	U	C	Searches	`_include`
AllergyIntolerance	https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance	y	y	y	y	patient, category, clinical-status, code, identifier, recorder, severity, _lastUpdated, patient
Condition	https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition	y	y	y	y	patient, category, code, encounter, identifier, onset-date, participant, severity, subject, _lastUpdated, patient	`Condition:encounter`
Consent	https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRConsent	y	y	y	y	patient
Encounter	https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHREncounter	y	y	y	y	patient, identifier, location, participant, participant-actor, status, subject, _lastUpdated, patient
Observation	https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRObservation	y	y	y	y	patient, category, code, date, encounter, identifier, performer, status, subject, value-concept, value-date, value-quantity, value-string, _lastUpdated, patient

Resource Conformance: supported AllergyIntolerance

Base System Profile
SDHRAllergyIntolerance

Profile Conformance
SHALL

Reference Policy

Interaction summary

Supports read, create, update, search-type.

Search Parameters

Conformance	Parameter	Type	Documentation
SHALL	patient	`reference`	MANDATORY Who the sensitivity is for Patient
SHALL	category	`token`	Must be one of food medication environment biologic AllergyIntolerance Category ValueSet
SHALL	clinical-status	`token`	Must be one of active inactive resolved AllergyIntolerance Clinical Status ValueSet
SHALL	code	`token`	Code that identifies the allergy or intolerance AllergyIntolerance Code ValueSet
SHALL	identifier	`token`	A unique identifier assigned to this resource.
SHALL	recorder	`reference`	Who recorded the sensitivity AllergyIntolerance.recorder
SHALL	severity	`token`	mild \| moderate \| severe (of event as a whole).
SHALL	_lastUpdated	`date`	When the resource version last changed

Combined Search Parameters

Conformance	Parameters	Types
SHALL	patient	`reference`

Resource Conformance: supported Condition

Base System Profile
SDHRCondition

Profile Conformance
SHALL

Reference Policy

Interaction summary

Supports read, create, update, search-type.

Search Parameters

Conformance	Parameter	Type	Documentation
SHALL	patient	`reference`	MANDATORY Who has the condition?
SHALL	category	`token`	The category of the condition
SHALL	code	`token`	The code for the condition
SHALL	encounter	`reference`	Encounter associated with the condition
SHALL	identifier	`token`	A unique identifier assigned to this resource.
SHALL	onset-date	`date`	Date the condition started
SHALL	participant	`reference`	Persons involved in the encounter other than the patient.
SHALL	severity	`token`	The severity of the condition
SHALL	subject	`reference`	Who has the condition?
SHALL	_lastUpdated	`date`	When the resource version last changed.

Combined Search Parameters

Conformance	Parameters	Types
SHALL	patient	`reference`

Resource Conformance: supported Consent

Base System Profile
SDHRConsent

Profile Conformance
SHALL

Reference Policy

Interaction summary

Supports read, create, update, search-type.

Search Parameters

Conformance	Parameter	Type	Documentation
SHALL	patient	`reference`	Who does the consent relate to

Resource Conformance: supported Encounter

Base System Profile
SDHREncounter

Profile Conformance
SHALL

Reference Policy

Interaction summary

Supports read, create, update, search-type.

Search Parameters

Conformance	Parameter	Type	Documentation
SHALL	patient	`reference`	MANDATORY The patient or group present at the encounter
SHALL	identifier	`token`	A unique identifier assigned to this resource.
SHALL	location	`reference`	Location the encounter takes place.
SHALL	participant	`reference`	Persons involved in the encounter other than the patient.
SHALL	participant-actor	`reference`	Persons involved in the encounter other than the patient.
SHALL	status	`token`	planned \| arrived \| triaged \| in-progress \| onleave \| finished \| cancelled +
SHALL	subject	`reference`	The patient or group present at the encounter
SHALL	_lastUpdated	`date`	When the resource version last changed.

Combined Search Parameters

Conformance	Parameters	Types
SHALL	patient	`reference`

Resource Conformance: supported Observation

Base System Profile
SDHRObservation

Profile Conformance
SHALL

Reference Policy

Interaction summary

Supports read, create, update, search-type.

Search Parameters

Conformance	Parameter	Type	Documentation
SHALL	patient	`reference`	MANDATORY Who the observation is for Patient
SHALL	category	`token`	The classification of the type of observation
SHALL	code	`token`	Describes what was observed. Sometimes this is called the observation 'name'
SHALL	date	`date`	Observation.effective Obtained date/time. If the obtained element is a period, a date that falls in the period
SHALL	encounter	`reference`	The Encounter resource associated with the Observation.
SHALL	identifier	`token`	A unique identifier assigned to this resource.
SHALL	performer	`reference`	Who performed the observation
SHALL	status	`token`	The status of the observation
SHALL	subject	`reference`	The subject that the observation is about
SHALL	value-concept	`token`	The value of the observation, if the value is a CodeableConcept
SHALL	value-date	`date`	The value of the observation, if the value is a date or period of time
SHALL	value-quantity	`quantity`	The value of the observation, if the value is a Quantity, or a SampledData (just search on the bounds of the values in sampled data)
SHALL	value-string	`string`	The value of the observation, if the value is a string, and also searches in CodeableConcept.text
SHALL	_lastUpdated	`date`	When the resource version last changed.

Combined Search Parameters

Conformance	Parameters	Types
SHALL	patient	`reference`

CapabilityStatement: NZ Shared Digital Health Record API