Health New Zealand Te Whatu Ora Shared Care FHIR API
0.4.1 - release New Zealand flag

Health New Zealand Te Whatu Ora Shared Care FHIR API - Local Development build (v0.4.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

This page describes how FHIR API-integrated applications can represent the two common forms of patient consent commonly sought in NZ health scenarios:

  1. Consent to collect patient information and share with other health NZ providers/practitioners through the FHIR API, and
  2. Consent to receive NZ health treatment or services.

Organisations providing health services, or collecting health information for the purpose of providing/coordinating health services, are required to obtain patient consent by NZ law and health policies. How those organisations actually obtain consent from the patient varies according to the processes each organisation uses, and these processes are external to Health New Zealand's FHIR API capability at present.

In the current period of adoption of FHIR APIs for health information interchange, it is assumed that official records of consent continue to be held in repositories of documentation specific to the organisations and the processes they operate. That is, FHIR consent representation, while necessary to share consent status easily through the sector as well as allow access control, is not the official record of patient consent.

The FHIR Consent representation described here allows for practical consideration that a patient's information may need to be appear in FHIR before their consent has been obtained. In rheumatic fever coordination, for example, patients are registered but sometimes not seen until a treatment appointment which is the first opportunity for them to sign a consent form.

To handle these scenarios, the FHIR API supports Consent instances created in a #proposed status, representing a provisional assumption of consent. Custodians can later convert such instances to #active status when consent is officially obtained.

When a patient declines to give their consent this may mean they have opted out of information collection/sharing or receiving treatment. FHIR supports both forms of consent using the two Consent scopes data-privacy and treatment.

Custodianship of patient health data

The organisation that collects patient information is the custodian of that data and organises creation of the corresponding FHIR Consents. The custodian org may or may not provide treatment but for FHIR representation, the key thing is that the party responsible for the patient data must be identified in the organisation element of the Consent instance. Organisation references should be formed using HPI organisation identifiers.

If management of a patient's information transfers to another organisation, the custodian organisation must be updated in Consent instances for that patient.


FHIR Consent instances for confirmed patient consentFHIR Consent instances for confirmed patient consent Representation of consent when confirmed by patient's signed form Patient data covered by data access provision3Consent to treatment:CONSENTstatus:#ACTIVEscope:#treatmentpolicy: reference to regs/leg.treatment provisiontype:#PERMITperiod:2023-01-21to2026-01-20Consent to collect/share data:CONSENTstatus:#ACTIVEscope:#patient-privacypolicy: reference to regs/leg.data access provisiontype:#PERMITperiod:2023-01-21to2026-01-20«logical reference»NHI patient:PATIENTlogical id: NHI«logical reference»Data custodian org:ORGANIZATIONHPI Org Id:GnXnnnplanned appointments, etc.:CAREPLAN meta.tag:#rf-nzcondition severity and specifics:CONDITION meta.tag:#rf-nzappointments:ENCOUNTER                                meta.tag:#rf-nzpreferences, health assessments:QUESTIONNAIRERESPONSE meta.tag:#rf-nzdiagnosis detail:OBSERVATION                          meta.tag:#rf-nz .provision .data.reference .patient2 .organizationHPI org. ref1 .patient .provision .organizationHPI org. ref1Notes1.Consent.organizationidentifies which org is custodian of the patient data.2. Consent instances identify the data subject in.patientreferences.3. FHIR resource instances with patient data tagged for access scoping eg. #rf-nz for rheumatic feverHealth NZ/Te Whatu Ora. FHIR data model generated on 11/04/2025



An error has occured : java.lang.IllegalStateExceptionHow about a nice game of chess? Diagram size: 127 lines / 4286 characters. PlantUML (1.2025.2) cannot parse result from dot/GraphViz. This version of PlantUML is 93 days old, so you shouldconsider upgrading from https://plantuml.com/download Please go to https://plantuml.com/graphviz-dot to check your GraphViz version. Java Runtime: OpenJDK Runtime EnvironmentJVM: OpenJDK 64-Bit Server VMDefault Encoding: UTF-8Language: enCountry: null PLANTUML_LIMIT_SIZE: 4096 This may be caused by :- a bug in PlantUML- a problem in GraphViz You should send this diagram and this image toplantuml@gmail.comorpost tohttps://plantuml.com/qato solve this issue.You can try to turn around this issue by simplifing your diagram. java.lang.IllegalStateExceptionnet.sourceforge.plantuml.svek.DotStringFactory.solve(DotStringFactory.java:378)net.sourceforge.plantuml.svek.GraphvizImageBuilder.buildImage(GraphvizImageBuilder.java:322)net.sourceforge.plantuml.svek.CucaDiagramFileMakerSvek.createFileInternal(CucaDiagramFileMakerSvek.java:142)net.sourceforge.plantuml.svek.CucaDiagramFileMakerSvek.createFile(CucaDiagramFileMakerSvek.java:108)net.atmp.CucaDiagram.exportDiagramInternal(CucaDiagram.java:527)net.sourceforge.plantuml.classdiagram.ClassDiagram.exportDiagramInternal(ClassDiagram.java:124)net.sourceforge.plantuml.UmlDiagram.exportDiagramNow(UmlDiagram.java:178)net.sourceforge.plantuml.AbstractPSystem.exportDiagram(AbstractPSystem.java:254)net.sourceforge.plantuml.PSystemUtils.exportDiagramsDefault(PSystemUtils.java:243)net.sourceforge.plantuml.PSystemUtils.exportDiagrams(PSystemUtils.java:133)net.sourceforge.plantuml.SourceFileReaderAbstract.getGeneratedImages(SourceFileReaderAbstract.java:229)net.sourceforge.plantuml.Run.manageFileInternal(Run.java:565)net.sourceforge.plantuml.Run.processArgs(Run.java:459)net.sourceforge.plantuml.Run.manageAllFiles(Run.java:426)net.sourceforge.plantuml.Run.main(Run.java:254)



Patient opted out from data sharing

FHIR Consent instances for patient opted-out (of treatment / data sharing)FHIR Consent instances for patient opted-out (of treatment / data sharing) Representation of consent denied (or withdrawn) by patient Patient data covered by data access provision3Consent to treatment:CONSENTstatus:#ACTIVEscope:#treatmentpolicy: reference to regs/leg.treatment provisiontype:#PERMITperiod:2023-01-21to2026-01-20Consent to collect/share data:CONSENTstatus:#ACTIVEscope:#patient-privacypolicy: reference to regs/leg.data access permit provisiontype:#DENYperiod:2023-06-23to..«logical reference»NHI patient:PATIENTlogical id: NHI«logical reference»Data custodian org:ORGANIZATIONHPI Org Id:GnXnnnplanned appointments, etc.:CAREPLAN meta.tag:#rf-nzcondition severity and specifics:CONDITION meta.tag:#rf-nzappointments:ENCOUNTER                                meta.tag:#rf-nzpreferences, health assessments:QUESTIONNAIRERESPONSE meta.tag:#rf-nzdiagnosis detail:OBSERVATION                          meta.tag:#rf-nz .provision .data.reference .patient2 .organizationHPI org. ref1 .patient .provision .organizationHPI org. ref1Notes1.Consent.organizationidentifies which org is custodian of the patient data.2. Consent instances identify the data subject in.patientreferences.3. FHIR resource instances with patient data tagged for access scoping eg. #rf-nz for rheumatic fever4. FHIR API access rules for instances covered by anopt-outconsents will becontrolled by OAUTH scopes TBDHealth NZ/Te Whatu Ora. FHIR data model generated on 11/04/2025



FHIR Consent instances when patient consent is pendingFHIR Consent instances when patient consent is pending Representation of limited provisional consent when patient's signed form pending but not received Patient data covered by temporary data access provision3consent to treatment:CONSENTstatus:#PROPOSEDscope:#treatmentpolicy: reference to regs/leg.treatment provisiontype:#PERMITperiod:2023-01-21to2026-01-20Consent to collect/share data:CONSENTstatus:#PROPOSEDscope:#patient-privacypolicy: reference to regs/leg.data access provisiontype:#PERMITperiod:2023-01-21to2026-01-20«logical reference»NHI patient:PATIENTlogical id: NHI«logical reference»Data custodian org:ORGANIZATIONHPI Org Id:GnXnnnplanned appointments, etc.:CAREPLAN meta.tag:#rf-nzcondition severity and specifics:CONDITION meta.tag:#rf-nzappointments:ENCOUNTER                                meta.tag:#rf-nzpreferences, health assessments:QUESTIONNAIRERESPONSE meta.tag:#rf-nzdiagnosis detail:OBSERVATION                          meta.tag:#rf-nz .provision .data.reference .patient2 .organizationHPI org. ref1 .patient .provision .organizationHPI org. ref1Notes1.Consent.organizationidentifies which org is custodian of the patient data.2. Consent instances identify the data subject in.patientreferences.3. FHIR resource instances with patient data tagged for access scoping eg. #rf-nz for rheumatic fever4. Start date is when the custodian provisionally-assumes consent to start;End date is empty (provision doesn't expire).Health NZ/Te Whatu Ora. FHIR data model generated on 11/04/2025