NZ Shared Digital Health Record API
1.1.6 - release

NZ Shared Digital Health Record API, published by Health New Zealand. This guide is not an authorized publication; it is the continuous build for version 1.1.6 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/tewhatuora/fhir-sdhr/ and changes regularly. See the Directory of published versions

API Documentation

The SDHR API comprises multiple FHIR resources. This page provides technical guidance for application developers integrating with the Shared Digital Health Record APIs.

The API Capability Statement defines supported FHIR interactions and request requirements. The FHIR artifacts provide the profiles, operation definitions, examples, and terminology used by the API, and the OpenAPI Specification provides a machine-readable interface description.

Authentication and request context

The SDHR API uses OAuth 2.0 client credentials. API consumers are authorised for approved interactions through the SDHR onboarding process.

The Request-Context header is required for API requests and supplies the user, organisation, facility, and other request context needed for authorisation and audit. X-Correlation-Id is optional and supports request tracing. The API Capability Statement and OpenAPI Specification define the technical header requirements.

Resource interaction catalogue

The following tables summarise the interactions intended for external API consumers contributing information to or accessing information from SDHR. The linked profiles, operation definitions, and detailed sections remain authoritative for parameters, payloads, response behaviour, validation, and errors.

Contributed resource interactions

Allergy, condition, and observation information is contributed to the SDHR Primary Care Collection. These resources support the same interaction pattern.

Resource Interactions HTTP verbs and relative URLs Profile or definition Detailed behaviour
AllergyIntolerance search, create, read, update GET /AllergyIntolerance
POST /AllergyIntolerance
GET /AllergyIntolerance/{id}
PUT /AllergyIntolerance/{id}		 SDHR AllergyIntolerance Search behaviour
Update behaviour
Condition search, create, read, update GET /Condition
POST /Condition
GET /Condition/{id}
PUT /Condition/{id}		 SDHR Condition Search behaviour
Update behaviour
Observation search, create, read, update GET /Observation
POST /Observation
GET /Observation/{id}
PUT /Observation/{id}		 SDHR Observation Search behaviour
Update behaviour

Batch interaction

Resource Interaction HTTP verb and relative URL Profile or definition Detailed behaviour
Bundle batch POST / SDHR Batch Bundle The Bundle must use type = batch; transaction processing and participation operations within the Bundle are not supported.

National source resource interactions

Medication and immunisation information is read-only through SDHR. It is sourced from national health information sources and cannot be created, updated, or deleted through the SDHR API.

Resource Interactions HTTP verbs and relative URLs Profile or definition Detailed behaviour
MedicationRequest search, read GET /MedicationRequest
GET /MedicationRequest/{id}		 SDHR MedicationRequest Search behaviour
MedicationDispense search, read GET /MedicationDispense
GET /MedicationDispense/{id}		 SDHR MedicationDispense Search behaviour
Immunization search, read GET /Immunization
GET /Immunization/{id}		 SDHR Immunization Search behaviour
Confidential record behaviour

Participation operations

Operation HTTP verb and relative URL Definition Status Detailed behaviour
$participate POST /$participate SDHR Participate Operation Active Technical contract
Contribution workflow
$participation-status POST /$participation-status SDHR Participation Status Operation Active Technical contract
Access information workflow

Access verification operation catalogue

Operation HTTP verb and relative URL Definition Status Detailed behaviour
$verification-samples GET /AuditEvent/$verification-samples SDHR Verification Samples Operation Draft Access verification operations
$verification-submissions POST /AuditEvent/$verification-submissions SDHR Verification Submissions Operation Draft Access verification operations

Logical view

SDHR API - Logical ViewSDHR API - Logical View«system»Secondary Care API Consumers«system»Secondary Care Systems«system»Primary Care API Consumers«system»Primary Care SystemsHealth NZ | Te Whatu Ora[system]HNZ Connector Plane[system]SDHR Data Services[system]«New-Capability»«system»FHIR APIsNational Dataservices[system]«Existing-Capability»«system»FHIR APIs«person»e.g. EmergencyDepartments,Hospitals Medical professionalsinvolved in secondarycare delivery«container»Regional ClinicalPortals«container»Regional SHERs«person»e.g. GeneralPractice Medical professionalsinvolved in primary caredelivery.«container»PatientManagementSystemsSDHR Condition FHIR APIConditionmethods(GET, POST,PUT)SDHR Observation FHIRAPIObservationmethods(GET, POST,PUT)SDHRMedicationRequest FHIRAPIMedicationRequestmethods(GET)SDHRMedicationDispenseFHIR APIMedicationDispensemethods(GET)SDHR AllergyIntoleranceFHIR APIAllergyIntolerancemethods(GET, POST,PUT)AIR Immunization FHIRAPIImmunizationmethods(GET, POST,PUT)Medicines DataRepository FHIR APIMedicationRequestMedicationDispensemethods(GET)Medical Warning SystemFHIR APIAlertmethods(GET, POST,PUT)National Health IndexPatientmethods(GET, POST,PUT)«person»Patients Patients using healthcare servicesGET prescriptionsGET dispensesLegend ▯ person ▯ system ▯ container ▯ system boundary ▯ New-Capability ▯ Existing-Capability 


API search behaviour

The Shared Digital Health Record FHIR API supports the FHIR search pattern.

Supported search parameters are listed in the API Capability Statement.

Medication and immunisation searches have source-specific filters, ordering, linked resources, paging and privacy responses. See medication search and paging behaviour and immunisation search and result behaviour.

See below for some example search queries.

Search for Conditions by patient and source

This query returns all Condition resources for a given Patient and meta.source.

GET /Condition?patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284&_source=https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ111-A

Click to view example response
In this example, the search returns two active conditions for patient `ZKC7284`, sourced from HPI location `FZZ111-A`. 

{
    "resourceType": "Bundle",
    "id": "92e3f5a6-2f8e-4e9d-a8f9-e5e6c578dd53",
    "meta": {
        "lastUpdated": "2025-05-01T21:23:04.818Z"
    },
    "type": "searchset",
    "total": 2,
    "link": [
        {
            "relation": "self",
            "url": "https://server.url/Condition?_source=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fhpi%2Fv1%2FLocation%2FFZZ111-A&patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC7284"
        }
    ],
    "entry": [
        {
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://server.url/Condition/635b2a1c-bdd1-4a20-8c2f-6d8348352f6a",
            "resource": {
                "identifier": [
                    {
                        "system": "https://standards.digital.health.nz/ns/health-record-key-id",
                        "value": "ef5b3aad-14c2-4904-aa25-7411dcb21327"
                    }
                ],
                "extension": [
                    {
                        "url": "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/hnz-sdhr-client-last-updated-extension",
                        "valueDateTime": "2025-03-20T09:14:00+13:00"
                    },
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/99ZZZZ",
                    "display": "Dottie McStuffins",
                    "type": "Practitioner"
                },
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "38341003",
                            "display": "HT - Hypertension"
                        }
                    ],
                    "text": "Hypertension"
                },
                "verificationStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                            "code": "confirmed"
                        }
                    ]
                },
                "subject": {
                    "reference": "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
                    "display": "Carrey Carrington",
                    "type": "Patient"
                },
                "recordedDate": "2023-11-26T10:02:45+13:00",
                "clinicalStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                            "code": "active"
                        }
                    ]
                },
                "onsetDateTime": "2011-02-05T00:00:00+13:00",
                "asserter": {
                    "reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN",
                    "display": "DR Julian Subatoi Bashir",
                    "type": "Practitioner"
                },
                "meta": {
                    "lastUpdated": "2025-03-21T00:34:52.819Z",
                    "versionId": "1",
                    "profile": [
                        "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition"
                    ],
                    "source": "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ111-A"
                },
                "id": "635b2a1c-bdd1-4a20-8c2f-6d8348352f6a",
                "resourceType": "Condition"
            }
        },
        {
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://server.url/Condition/c3605e85-6785-4fa9-94a5-6d8015416c53",
            "resource": {
                "extension": [
                    {
                        "url": "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/hnz-sdhr-client-last-updated-extension",
                        "valueDateTime": "2025-03-20T09:17:00+13:00"
                    },
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/99ZZZZ",
                    "display": "Dottie McStuffins",
                    "type": "Practitioner"
                },
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "13645005",
                            "display": "Chronic obstructive pulmonary disease"
                        }
                    ],
                    "text": "Hypertension"
                },
                "verificationStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                            "code": "confirmed"
                        }
                    ]
                },
                "subject": {
                    "reference": "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
                    "display": "Carrey Carrington",
                    "type": "Patient"
                },
                "recordedDate": "2023-11-26T10:02:45+13:00",
                "clinicalStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                            "code": "active"
                        }
                    ]
                },
                "onsetDateTime": "2011-02-05T00:00:00+13:00",
                "asserter": {
                    "reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN",
                    "display": "DR Julian Subatoi Bashir",
                    "type": "Practitioner"
                },
                "meta": {
                    "lastUpdated": "2025-03-21T00:41:35.416Z",
                    "versionId": "1",
                    "profile": [
                        "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition"
                    ],
                    "source": "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ111-A"
                },
                "id": "c3605e85-6785-4fa9-94a5-6d8015416c53",
                "resourceType": "Condition"
            }
        }
    ]
}


Search for resources by patient and identifier

The identifier search parameter can be used with unique source-system identifiers. This enables systems such as PMS products to locate resources using identifiers they assigned and retained. A resource can contain multiple identifiers.

Request Condition resources for a specific identifier GET Condition?patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284&identifier=38cb6f26-9534-46e5-b659-536992faf0cc

Request Condition resources for a specific identifier AND system, GET /Condition?patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284&identifier=https://some.local.system/ehr-key%7Cd2ed3bc7-da4a-45b8-ae3f-82176f5c64a4

Click to view example response
In this example, the query returns a single result. 


{
    "resourceType": "Bundle",
    "id": "4c3cf2a4-4424-46f4-b4af-00c46812ec7e",
    "meta": {
        "lastUpdated": "2025-05-01T22:23:57.904Z"
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://server.url/Condition?identifier=38cb6f26-9534-46e5-b659-536992faf0cc&patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC7284"
        }
    ],
    "entry": [
        {
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://server.url/Condition/72ca633a-23cc-4848-a512-5111750508fb",
            "resource": {
                "identifier": [
                    {
                        "system": "https://some.local.system/ehr-key",
                        "value": "38cb6f26-9534-46e5-b659-536992faf0cc"
                    }
                ],
                "extension": [
                    {
                        "url": "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/hnz-sdhr-client-last-updated-extension",
                        "valueDateTime": "2025-05-01T09:02:00+13:00"
                    },
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/99ZZZZ",
                    "display": "Dottie McStuffins",
                    "type": "Practitioner"
                },
                "code": {
                    "coding": [
                        {
                            "system": "http://health.govt.nz/read-codes",
                            "code": "SN3..",
                            "display": "Local pressure"
                        }
                    ],
                    "text": "Hypertension"
                },
                "verificationStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                            "code": "confirmed"
                        }
                    ]
                },
                "subject": {
                    "reference": "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
                    "display": "Carrey Carrington",
                    "type": "Patient"
                },
                "recordedDate": "2023-11-26T10:02:45+13:00",
                "clinicalStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                            "code": "active"
                        }
                    ]
                },
                "onsetDateTime": "2011-02-05T00:00:00+13:00",
                "asserter": {
                    "reference": "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN",
                    "display": "DR Julian Subatoi Bashir",
                    "type": "Practitioner"
                },
                "meta": {
                    "lastUpdated": "2025-05-01T22:23:37.587Z",
                    "versionId": "1",
                    "profile": [
                        "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition"
                    ],
                    "source": "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ111-A"
                },
                "id": "72ca633a-23cc-4848-a512-5111750508fb",
                "resourceType": "Condition"
            }
        }
    ]
}


SDHR resource updates

This section describes how an API consumer interacts with the SDHR FHIR server to update existing resources.

GET before PUT

To maintain data integrity, API consumers authorised to update resources must use a "GET before PUT" approach. Fetching the current resource before updating it ensures that changes are based on the latest state and do not overwrite updates made by another API consumer.

Shared Digital Health Record - GET before PUTShared Digital Health Record - GET before PUTSDHR FHIR ServerSDHR FHIR ServerAPI ConsumerSDHR FHIR ServerAPI ConsumerAPI ConsumerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerPOST /Condition (Create)201 Created, serverResourceId returnedTime passes, the resource has been updated at sourceGET /Condition/{serverResourceId} (Read current resource)Make changes to resource, e.g. update statusPUT /Condition/{serverResourceId} (Update resource)200 OK


Searching for resources before update

The API Capability Statement documents the supported FHIR search parameters and direct read interactions.

Case 1: The server-assigned resource ID is known

Retrieve the resource directly using GET /Condition/{serverResourceId}.

After applying the required changes, update the resource using PUT /Condition/{serverResourceId}.

Case 2: The server-assigned resource ID is unknown

Use a FHIR search with parameters available to the API consumer to locate the resource before updating it.

Option 1: FHIR Search by local PMS identifier, stored as a FHIR Identifier

API consumers that create or update records may include a source-system identifier in the shared resource. When this identifier is retained locally, the API consumer can use the identifier search parameter to locate the resource.

Shared Digital Health Record - FHIR Search by identifierShared Digital Health Record - FHIR Search by identifierSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerAPI ConsumerSDHR FHIR ServerAPI ConsumerAPI ConsumerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerPOST /Condition (Create, including local identifier)201 Created, serverResourceId returnedTime passes, the resource has been updated at sourceGET /Condition?identifier=&_source=https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ111-A(Search by identifier and facilityId)Bundle (Containing Condition Resource)Make changes to resource, e.g. update statusPUT /Condition/{serverResourceId} (Update)200 OK


Option 2: FHIR Search using resource search parameters

When a source-system identifier is unavailable, use the resource-specific parameters documented in the API Capability Statement. The search returns a FHIR Bundle that may contain multiple matches, which the API consumer must handle safely.

Shared Digital Health Record - FHIR Search by known parametersShared Digital Health Record - FHIR Search by known parametersSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerAPI ConsumerSDHR FHIR ServerAPI ConsumerAPI ConsumerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerPOST /Condition (Create)201 Created, serverResourceId returnedTime passes, the resource has been updated at sourceGET /Condition?code=http:snomed.info/sct|442387007&status=active&subject=https:api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284(Search by subject, status and code)Bundle (Containing Condition Resource)Make changes to resource, e.g. update statusPUT /Condition/{serverResourceId} (Update)200 OK


SDHR custom operations

The SDHR service includes the following FHIR custom operations.

Access verification operations

Draft: These verification operations and examples are currently draft and should be treated as draft interface content.

SEHR systems need to periodically retrieve sampled access events from SDHR, review whether those accesses were valid, and submit the verification decisions. Samples are represented as FHIR AuditEvent resources that conform to the SDHR AuditEvent profile.

SDHR identifies eligible data viewers from Keycloak service-account users with the SDHR_Audit role, resolving each service-account user to its owning application’s client UUID. For each eligible viewer, it requests a sample from the upstream AuditEvents service over the preceding 24-hour window, scoped to the deployed SDHR service. The configured sampling proportion defaults to 0.02 (2%). SDHR checks each returned event for the matching client and a single identified clinician requestor before importing it. It checks the source-system ID and exact viewer identity to avoid importing the same event again. Each imported sample receives a new SDHR logical ID. Source-system identity and verification state remain internal. The application identity remains in the original agent array.

Sampling runs independently of retrieval requests. This workflow is performed on an ongoing basis so that newly sampled access events continue to be reviewed and verified over time.

The end-to-end sequence and corresponding processing steps are documented in the audit access records workflow.

Retrieve verification samples

Each sample includes its SDHR logical ID, event type, recorded time and the original agent array, unchanged. This preserves each agent’s roles, requestor flag, identity and other supplied fields. The application agent has the dataprocessor role and carries its Keycloak client UUID in who.identifier; source events that use who.display retain that representation. Client ownership is checked against this application agent, not against the requestor flag. The separate healthworker agent carries the clinician’s HPI person identifier, and an organisation agent may carry its HPI organisation identifier. Use the clinician identity together with the patient NHI and recorded time to assess whether the clinician had a valid reason to access the patient’s information. When available, NHI and request correlation IDs appear as string-valued entity.detail entries with types nhi and correlationId in a single entity. Repeated identical type/value pairs are removed; missing details are omitted. entity.what is omitted. FHIR R4 requires source.observer; samples therefore retain only its neutral display, "SDHR verification samples", without internal source identity.

The SEHR calls GET /AuditEvent/$verification-samples to retrieve a Bundle of sampled AuditEvent resources that require verification. The operation supports _count and _getpagesoffset query parameters for paging, for example:

GET /AuditEvent/$verification-samples?_count=1&_getpagesoffset=0

The caller is identified by the authenticated client_id; callers cannot select another client through request parameters. Successful requests always return a searchset Bundle, which may be empty. Retrieval does not register clients or initiate sampling.

Follow the returned paging links, which remain on $verification-samples, rather than constructing generic AuditEvent searches. Generic AuditEvent read, search and write routes are unavailable. Pending results change after submissions, so retrieve all pages before submitting decisions, or restart at the first page after submissions rather than continuing an old offset.

See SDHRVerificationSamplesOperation.

Click to view verification samples Bundle example 
{
  "resourceType" : "Bundle",
  "id" : "BundleVerificationSamplesResponseExample",
  "type" : "searchset",
  "timestamp" : "2026-07-03T10:00:00+12:00",
  "total" : 2,
  "link" : [
    {
      "relation" : "self",
      "url" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/$verification-samples"
    }
  ],
  "entry" : [
    {
      "fullUrl" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/b3f9de58-2da4-427c-a39c-07147eac3615",
      "resource" : {
        "resourceType" : "AuditEvent",
        "id" : "b3f9de58-2da4-427c-a39c-07147eac3615",
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><a name=\"AuditEvent_b3f9de58-2da4-427c-a39c-07147eac3615\"> </a><p class=\"res-header-id\"><b>Generated Narrative: AuditEvent b3f9de58-2da4-427c-a39c-07147eac3615</b></p><a name=\"b3f9de58-2da4-427c-a39c-07147eac3615\"> </a><a name=\"hcb3f9de58-2da4-427c-a39c-07147eac3615\"> </a><p><b>type</b>: <a href=\"http://terminology.hl7.org/7.4.0/CodeSystem-audit-event-type.html#audit-event-type-rest\">Audit Event ID: rest</a> (RESTful Operation)</p><p><b>recorded</b>: 2026-07-03 09:15:00+1200</p><blockquote><p><b>agent</b></p><p><b>role</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/extra-security-role-type dataprocessor}\">Data Processor</span></p><p><b>who</b>: Identifier: <code>https://api.auth.digital.health.nz/realms/hnz-integration/clients</code>/2b628d46-bdad-4f91-a3b0-c26e058c7d24</p><p><b>requestor</b>: false</p></blockquote><blockquote><p><b>agent</b></p><p><b>role</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/v3-RoleClass PROV}\">healthcare provider</span></p><p><b>who</b>: Identifier: HPIProvider/99ZZFX</p><p><b>requestor</b>: true</p></blockquote><blockquote><p><b>agent</b></p><p><b>role</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/v3-RoleClass PROV}\">healthcare provider</span></p><p><b>who</b>: Identifier: HPIOrganization/GZZ999</p><p><b>requestor</b>: false</p></blockquote><h3>Sources</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Observer</b></td></tr><tr><td style=\"display: none\">*</td><td>SDHR verification samples</td></tr></table><blockquote><p><b>entity</b></p><blockquote><p><b>detail</b></p><p><b>type</b>: nhi</p><p><b>value</b>: ZZZ0004</p></blockquote><blockquote><p><b>detail</b></p><p><b>type</b>: correlationId</p><p><b>value</b>: c500dae6-ac65-4e4f-a4c1-5aa222a6a807</p></blockquote></blockquote></div>"
        },
        "type" : {
          "system" : "http://terminology.hl7.org/CodeSystem/audit-event-type",
          "code" : "rest"
        },
        "recorded" : "2026-07-03T09:15:00+12:00",
        "agent" : [
          {
            "role" : [
              {
                "coding" : [
                  {
                    "system" : "http://terminology.hl7.org/CodeSystem/extra-security-role-type",
                    "code" : "dataprocessor"
                  }
                ]
              }
            ],
            "who" : {
              "identifier" : {
                "system" : "https://api.auth.digital.health.nz/realms/hnz-integration/clients",
                "value" : "2b628d46-bdad-4f91-a3b0-c26e058c7d24"
              }
            },
            "requestor" : false
          },
          {
            "role" : [
              {
                "coding" : [
                  {
                    "system" : "http://terminology.hl7.org/CodeSystem/v3-RoleClass",
                    "code" : "PROV"
                  }
                ]
              }
            ],
            "who" : {
              "identifier" : {
                "system" : "https://standards.digital.health.nz/ns/hpi-person-id",
                "value" : "99ZZFX"
              }
            },
            "requestor" : true
          },
          {
            "role" : [
              {
                "coding" : [
                  {
                    "system" : "http://terminology.hl7.org/CodeSystem/v3-RoleClass",
                    "code" : "PROV"
                  }
                ]
              }
            ],
            "who" : {
              "identifier" : {
                "system" : "https://standards.digital.health.nz/ns/hpi-organisation-id",
                "value" : "GZZ999"
              }
            },
            "requestor" : false
          }
        ],
        "source" : {
          "observer" : {
            "display" : "SDHR verification samples"
          }
        },
        "entity" : [
          {
            "detail" : [
              {
                "type" : "nhi",
                "valueString" : "ZZZ0004"
              },
              {
                "type" : "correlationId",
                "valueString" : "c500dae6-ac65-4e4f-a4c1-5aa222a6a807"
              }
            ]
          }
        ]
      }
    },
    {
      "fullUrl" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/6ebffb1a-61a1-4646-857e-51d4153b698d",
      "resource" : {
        "resourceType" : "AuditEvent",
        "id" : "6ebffb1a-61a1-4646-857e-51d4153b698d",
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><a name=\"AuditEvent_6ebffb1a-61a1-4646-857e-51d4153b698d\"> </a><p class=\"res-header-id\"><b>Generated Narrative: AuditEvent 6ebffb1a-61a1-4646-857e-51d4153b698d</b></p><a name=\"6ebffb1a-61a1-4646-857e-51d4153b698d\"> </a><a name=\"hc6ebffb1a-61a1-4646-857e-51d4153b698d\"> </a><p><b>type</b>: <a href=\"http://terminology.hl7.org/7.4.0/CodeSystem-audit-event-type.html#audit-event-type-rest\">Audit Event ID: rest</a> (RESTful Operation)</p><p><b>recorded</b>: 2026-07-03 09:20:00+1200</p><blockquote><p><b>agent</b></p><p><b>role</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/extra-security-role-type dataprocessor}\">Data Processor</span></p><p><b>who</b>: Identifier: <code>https://api.auth.digital.health.nz/realms/hnz-integration/clients</code>/2b628d46-bdad-4f91-a3b0-c26e058c7d24</p><p><b>requestor</b>: false</p></blockquote><blockquote><p><b>agent</b></p><p><b>role</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/v3-RoleClass PROV}\">healthcare provider</span></p><p><b>who</b>: Identifier: HPIProvider/99ZZFX</p><p><b>requestor</b>: true</p></blockquote><blockquote><p><b>agent</b></p><p><b>role</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/v3-RoleClass PROV}\">healthcare provider</span></p><p><b>who</b>: Identifier: HPIOrganization/GZZ999</p><p><b>requestor</b>: false</p></blockquote><h3>Sources</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Observer</b></td></tr><tr><td style=\"display: none\">*</td><td>SDHR verification samples</td></tr></table><blockquote><p><b>entity</b></p><blockquote><p><b>detail</b></p><p><b>type</b>: nhi</p><p><b>value</b>: ZZZ0004</p></blockquote><blockquote><p><b>detail</b></p><p><b>type</b>: correlationId</p><p><b>value</b>: c500dae6-ac65-4e4f-a4c1-5aa222a6a807</p></blockquote></blockquote></div>"
        },
        "type" : {
          "system" : "http://terminology.hl7.org/CodeSystem/audit-event-type",
          "code" : "rest"
        },
        "recorded" : "2026-07-03T09:20:00+12:00",
        "agent" : [
          {
            "role" : [
              {
                "coding" : [
                  {
                    "system" : "http://terminology.hl7.org/CodeSystem/extra-security-role-type",
                    "code" : "dataprocessor"
                  }
                ]
              }
            ],
            "who" : {
              "identifier" : {
                "system" : "https://api.auth.digital.health.nz/realms/hnz-integration/clients",
                "value" : "2b628d46-bdad-4f91-a3b0-c26e058c7d24"
              }
            },
            "requestor" : false
          },
          {
            "role" : [
              {
                "coding" : [
                  {
                    "system" : "http://terminology.hl7.org/CodeSystem/v3-RoleClass",
                    "code" : "PROV"
                  }
                ]
              }
            ],
            "who" : {
              "identifier" : {
                "system" : "https://standards.digital.health.nz/ns/hpi-person-id",
                "value" : "99ZZFX"
              }
            },
            "requestor" : true
          },
          {
            "role" : [
              {
                "coding" : [
                  {
                    "system" : "http://terminology.hl7.org/CodeSystem/v3-RoleClass",
                    "code" : "PROV"
                  }
                ]
              }
            ],
            "who" : {
              "identifier" : {
                "system" : "https://standards.digital.health.nz/ns/hpi-organisation-id",
                "value" : "GZZ999"
              }
            },
            "requestor" : false
          }
        ],
        "source" : {
          "observer" : {
            "display" : "SDHR verification samples"
          }
        },
        "entity" : [
          {
            "detail" : [
              {
                "type" : "nhi",
                "valueString" : "ZZZ0004"
              },
              {
                "type" : "correlationId",
                "valueString" : "c500dae6-ac65-4e4f-a4c1-5aa222a6a807"
              }
            ]
          }
        ]
      }
    }
  ]
}

An empty samples Bundle is a normal response when no samples are pending for the authenticated client.

Review sampled access events

The SEHR reviews the returned AuditEvent resources using either an automated process or a manual workflow to determine whether each recorded access was valid.

Submit verification decisions

The SEHR calls POST /AuditEvent/$verification-submissions with the defined Parameters payload to submit 1 to 100 verification decisions per request. Requests containing more than 100 verification parameters return HTTP 400 before any decisions are processed. For larger sets, submit multiple requests.

Submit validated or validation-failed for each sample, referencing its local AuditEvent/{id} (a full HTTP(S) URL ending in that path is also accepted). Each item is processed independently and its response is returned in submission order. A processed decision removes that sample from the pending set for either result. Repeating a decision for an already verified sample returns already-processed; the saved decision is unchanged.

This case-sensitive code system https://fhir-ig.digital.health.nz/sdhr/CodeSystem/sdhr-verification-submission-status defines the following codes:

CodeDisplayDefinition
processed Processed Decision saved.
not-found Not found No local sample is available to the authenticated client.
already-processed Already processed The sample decision was already processed; the saved decision is unchanged.
invalid Invalid Reference or result is missing or invalid.
error Error An unexpected persistence failure prevented processing this item.

A response may contain mixed statuses; inspect every item rather than treating HTTP success as confirmation that all decisions were saved.

See SDHRVerificationSubmissionsOperation, the SDHRVerificationSubmissionParameters profile, and the SDHRVerificationSubmissionResponseParameters profile.

Click to view verification submission request example 
{
  "resourceType" : "Parameters",
  "id" : "ParametersVerificationSubmissionRequestExample",
  "meta" : {
    "profile" : [
      🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRVerificationSubmissionParameters"
    ]
  },
  "parameter" : [
    {
      "name" : "verification",
      "part" : [
        {
          "name" : "auditEvent",
          "valueReference" : {
            "reference" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/b3f9de58-2da4-427c-a39c-07147eac3615"
          }
        },
        {
          "name" : "result",
          "valueCode" : "validated"
        }
      ]
    },
    {
      "name" : "verification",
      "part" : [
        {
          "name" : "auditEvent",
          "valueReference" : {
            "reference" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/6ebffb1a-61a1-4646-857e-51d4153b698d"
          }
        },
        {
          "name" : "result",
          "valueCode" : "validation-failed"
        }
      ]
    }
  ]
}
Click to view verification submission response example 
{
  "resourceType" : "Parameters",
  "id" : "ParametersVerificationSubmissionResponseExample",
  "meta" : {
    "profile" : [
      🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRVerificationSubmissionResponseParameters"
    ]
  },
  "parameter" : [
    {
      "name" : "verificationSubmissionResult",
      "part" : [
        {
          "name" : "auditEvent",
          "valueReference" : {
            "reference" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/b3f9de58-2da4-427c-a39c-07147eac3615"
          }
        },
        {
          "name" : "status",
          "valueCode" : "processed"
        }
      ]
    },
    {
      "name" : "verificationSubmissionResult",
      "part" : [
        {
          "name" : "auditEvent",
          "valueReference" : {
            "reference" : "https://api.uat.sdhr.digital.health.nz/s2s/AuditEvent/6ebffb1a-61a1-4646-857e-51d4153b698d"
          }
        },
        {
          "name" : "status",
          "valueCode" : "processed"
        }
      ]
    }
  ]
}

For a repeated submission, see the already-processed response example.

Participate operation

The $participate operation enables API consumers, such as PMS products, to record a patient's facility participation preference and record-level withholding or release.

Contract element Requirement
Interaction System-level custom operation
HTTP request POST /$participate
Definition SDHR Participate Operation
Request body FHIR Parameters conforming to the operation definition
Response body OperationOutcome indicating success or failure
Behaviour Idempotent for repeated requests with the same parameters

The operation supports facility opt-out and opt-back-in, technical initialisation of the default facility preference, withholding a local Condition or Observation, and releasing a previously withheld record. A facility opt-out archives the patient's active contributed resources from that facility; archived resources are retained but are excluded from normal search and read interactions. Parameter cardinalities, conditional requirements, bindings, and response definitions are authoritative in the OperationDefinition.

Request examples:

Response examples:

Example request to release a withheld record 
{
  "resourceType" : "Parameters",
  "id" : "ParametersParticipateRecordReleased",
  "parameter" : [
    {
      "name" : "patient",
      "valueReference" : {
        "reference" : "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
        "type" : "Patient",
        "display" : "Susan Westbrook"
      }
    },
    {
      "name" : "facilityId",
      "valueReference" : {
        "reference" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ111-A"
      }
    },
    {
      "name" : "resourceType",
      "valueString" : "Condition"
    },
    {
      "name" : "localResourceId",
      "valueString" : "12345AAABBBccc"
    },
    {
      "name" : "reasonCode",
      "valueCoding" : {
        "system" : "https://fhir-ig.digital.health.nz/sdhr/CodeSystem/sdhr-participation-reason",
        "code" : "sdhr-record-released",
        "display" : "Record released"
      }
    }
  ]
}

See Manage participation for the end-to-end facility, Health NZ, confidentiality, and historical-reload workflows. UAT identities and expected deny or lock outcomes are documented under Test Data.

Participation status operation

The $participation-status operation allows an SEHR system to check whether a patient is globally participating in SDHR before requesting health information. It returns only the hnzParticipationIndicator boolean. The operation does not change the patient's participation preference and does not return clinical information.

Contract element Requirement
Interaction System-level custom operation
HTTP request POST /$participation-status
Definition SDHR Participation Status Operation
Request body FHIR Parameters containing one NHI patient reference
Required SMART scope https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipationStatusOperation
Response body FHIR Parameters containing only hnzParticipationIndicator
hnzParticipationIndicator true indicates global participation, including when no global preference is recorded; false indicates that the patient has opted out globally

The operation is intended to be called by a healthcare provider on behalf of the patient. The patient must be identified by an NHI. The status returned is global; it does not represent a facility-level participation preference.

Request example:

Response examples:

SEHR systems should use the result to determine whether to continue with an information request. If hnzParticipationIndicator is false, the patient is globally opted out of SDHR and no information will be available for that patient.

Global participation denial API behaviour

When a resource read or search request is rejected by the global participation consent check, SDHR returns HTTP 403 with an OperationOutcome rather than clinical data. This applies to contributed resources and proxied national datasets, including AIR immunisations.

The global opt-out reason is recorded in the root Consent.provision.extension with URL https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/hnz-global-opt-out-reason-extension. When Consent.provision.type is deny and the extension's valueCode is patient-deceased, the response uses sdhr-participation-status-denied-deceased from the SDHR outcome CodeSystem.

The response message is:

Patient data is unavailable in the Shared Digital Health Record as they are deceased.

Response status: 403

Response body:

{
  "resourceType" : "OperationOutcome",
  "id" : "OperationOutcomeGlobalDenyDeceasedExample",
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: OperationOutcome OperationOutcomeGlobalDenyDeceasedExample</b></p><a name=\"OperationOutcomeGlobalDenyDeceasedExample\"> </a><a name=\"hcOperationOutcomeGlobalDenyDeceasedExample\"> </a><h3>Issues</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Severity</b></td><td><b>Code</b></td><td><b>Details</b></td></tr><tr><td style=\"display: none\">*</td><td>Error</td><td>Information  Suppressed</td><td><span title=\"Codes:{https://fhir-ig.digital.health.nz/sdhr/CodeSystem/sdhr-outcome-codes sdhr-participation-status-denied-deceased}\">Patient data is unavailable in the Shared Digital Health Record as they are deceased.</span></td></tr></table></div>"
  },
  "issue" : [
    {
      "severity" : "error",
      "code" : "suppressed",
      "details" : {
        "coding" : [
          {
            "system" : "https://fhir-ig.digital.health.nz/sdhr/CodeSystem/sdhr-outcome-codes",
            "code" : "sdhr-participation-status-denied-deceased",
            "display" : "SDHR Participation Status Denied - Patient Deceased"
          }
        ],
        "text" : "Patient data is unavailable in the Shared Digital Health Record as they are deceased."
      }
    }
  ]
}

See deceased global-denial example

Global opt-outs with other reasons, including patient-choice and imported-external-consent, or without a recorded reason, retain the generic global-denial outcome with code sdhr-participation-status-denied. Write requests also retain the generic global-denial outcome, including when the recorded reason is patient-deceased.

This response reflects a recorded global consent decision; it does not perform a new deceased-status lookup. A death reason on a permitting consent does not trigger this response. Archived contributed records remain unavailable through normal reads, and a read rejected before consent evaluation does not necessarily return this outcome.

The $hnz-participate operation still returns its normal success outcome when it records the opt-out. The $participation-status operation remains unchanged: it returns Parameters containing the participation indicator and does not expose the global opt-out reason.

Accessing systems must use the outcome code to distinguish deceased global denial from other global opt-outs and inform clinical users as required by SRD-16.

SDHR confidential record API behaviour

SDHR represents two distinct confidentiality cases: an SDHR resource carrying a restrictive FHIR security label, and a source record registered as withheld through $participate where the clinical resource is not stored in SDHR. Their API responses differ. National-source proxy responses also have specific rules: see medication privacy responses and AIR restricted access responses.

Stored resource security-label behaviour

Confidentiality labels are applied to an SDHR resource through its meta.security array using the http://terminology.hl7.org/CodeSystem/v3-Confidentiality code system.

The behaviours below apply to resources labelled R (Restricted) or V (Very Restricted). SDHR resources without either confidentiality label are not subject to these behaviours.

Sample confidential resource
Click to view example confidential resource 
{
  "resourceType" : "AllergyIntolerance",
  "id" : "AllergyIntoleranceExample",
  "meta" : {
    "lastUpdated" : "2024-01-26T10:03:26+13:00",
    "source" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B",
    "profile" : [
      🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance"
    ],
    "security" : [
      {
        "system" : "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
        "code" : "R",
        "display" : "Restricted"
      }
    ]
  },
  "text" : {
    "status" : "extensions",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: AllergyIntolerance AllergyIntoleranceExample</b></p><a name=\"AllergyIntoleranceExample\"> </a><a name=\"hcAllergyIntoleranceExample\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Last updated: 2024-01-26 10:03:26+1300; </p><p style=\"margin-bottom: 0px\">Information Source: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&amp;canonical=https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B\">https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B</a></p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-SDHRAllergyIntolerance.html\">SDHRAllergyIntolerance</a></p><p style=\"margin-bottom: 0px\">Security Label: <a href=\"http://terminology.hl7.org/7.4.0/CodeSystem-v3-Confidentiality.html\">Restricted (Details: Confidentiality code R = 'Restricted')</a></p></div><p><b>Client Last Updated</b>: 2023-11-26 10:02:45+1300</p><p><b>identifier</b>: <code>https://fhir.examplepms.co.nz</code>/ec2d6cad-1e19-46ee-accf-dc460a680710\u00a0(use:\u00a0secondary)</p><p><b>clinicalStatus</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical active}\">Active</span></p><p><b>verificationStatus</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/allergyintolerance-verification confirmed}\">Confirmed</span></p><p><b>type</b>: Allergy</p><p><b>category</b>: Medication</p><p><b>code</b>: <span title=\"Codes:{http://snomed.info/sct 91936005}\">Allergy to penicillin (finding)</span></p><p><b>patient</b>: <a href=\"Bundle-HIPReferenceTargets.html#https-//api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284\">Sage Westbrook</a></p><p><b>recorder</b>: <a href=\"Bundle-HIPReferenceTargets.html#https-//api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN\">DR Julian Subatoi Bashir</a></p></div>"
  },
  "extension" : [
    {
      "url" : "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/hnz-sdhr-client-last-updated-extension",
      "valueDateTime" : "2023-11-26T10:02:45+13:00"
    }
  ],
  "identifier" : [
    {
      "use" : "secondary",
      "system" : "https://fhir.examplepms.co.nz",
      "value" : "ec2d6cad-1e19-46ee-accf-dc460a680710"
    }
  ],
  "clinicalStatus" : {
    "coding" : [
      {
        "system" : "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
        "code" : "active",
        "display" : "Active"
      }
    ]
  },
  "verificationStatus" : {
    "coding" : [
      {
        "system" : "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
        "code" : "confirmed",
        "display" : "Confirmed"
      }
    ]
  },
  "type" : "allergy",
  "category" : [
    "medication"
  ],
  "code" : {
    "coding" : [
      {
        "system" : "http://snomed.info/sct",
        "code" : "91936005",
        "display" : "Allergy to penicillin (finding)",
        "userSelected" : true
      }
    ]
  },
  "patient" : {
    "reference" : "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
    "type" : "Patient",
    "display" : "Sage Westbrook"
  },
  "recorder" : {
    "reference" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN",
    "type" : "Practitioner",
    "display" : "DR Julian Subatoi Bashir"
  }
}
Search response

GET /AllergyIntolerance?patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC7284

Response status: 200

Response body:

Click to view example response 
{
  "resourceType" : "Bundle",
  "id" : "SearchConfidentialRecordsResponseExample",
  "meta" : {
    "lastUpdated" : "2025-04-29T23:35:29.795Z",
    "security" : [
      {
        "system" : "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
        "code" : "redacted",
        "display" : "REDACTED"
      }
    ]
  },
  "type" : "searchset",
  "total" : 2,
  "link" : [
    {
      "relation" : "self",
      "url" : "https://api.mock.sdhr.digital.health.nz/s2s/AllergyIntolerance?patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC7284"
    }
  ],
  "entry" : [
    {
      "fullUrl" : "https://api.mock.sdhr.digital.health.nz/s2s/AllergyIntolerance/AllergyIntoleranceExample2",
      "resource" : {
        "resourceType" : "AllergyIntolerance",
        "id" : "AllergyIntoleranceExample2",
        "meta" : {
          "lastUpdated" : "2024-01-26T10:03:26+13:00",
          "source" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B",
          "profile" : [
            🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance"
          ]
        },
        "text" : {
          "status" : "extensions",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><a name=\"AllergyIntolerance_AllergyIntoleranceExample2\"> </a><p class=\"res-header-id\"><b>Generated Narrative: AllergyIntolerance AllergyIntoleranceExample2</b></p><a name=\"AllergyIntoleranceExample2\"> </a><a name=\"hcAllergyIntoleranceExample2\"> </a><div style=\"display: inline-block; background-color: #d9e0e7; padding: 6px; margin: 4px; border: 1px solid #8da1b4; border-radius: 5px; line-height: 60%\"><p style=\"margin-bottom: 0px\">Last updated: 2024-01-26 10:03:26+1300; </p><p style=\"margin-bottom: 0px\">Information Source: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&amp;canonical=https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B\">https://api.hip.digital.health.nz/fhir/hpi/v1/Location/F38006-B</a></p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-SDHRAllergyIntolerance.html\">SDHRAllergyIntolerance</a></p></div><p><b>Client Last Updated</b>: 2024-02-14 11:15:00+1300</p><p><b>identifier</b>: <code>https://fhir.examplepms.co.nz</code>/ec2d6cad-1e19-46ee-accf-dc460a680710\u00a0(use:\u00a0secondary)</p><p><b>clinicalStatus</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical active}\">Active</span></p><p><b>verificationStatus</b>: <span title=\"Codes:{http://terminology.hl7.org/CodeSystem/allergyintolerance-verification confirmed}\">Confirmed</span></p><p><b>type</b>: Allergy</p><p><b>category</b>: Food</p><p><b>code</b>: <span title=\"Codes:{http://snomed.info/sct 227493005}\">Cashew nuts</span></p><p><b>patient</b>: <a href=\"Bundle-HIPReferenceTargets.html#https-//api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284\">Sage Westbrook</a></p><p><b>recorder</b>: <a href=\"Bundle-HIPReferenceTargets.html#https-//api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN\">DR Julian Subatoi Bashir</a></p></div>"
        },
        "extension" : [
          {
            "url" : "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/hnz-sdhr-client-last-updated-extension",
            "valueDateTime" : "2024-02-14T11:15:00+13:00"
          }
        ],
        "identifier" : [
          {
            "use" : "secondary",
            "system" : "https://fhir.examplepms.co.nz",
            "value" : "ec2d6cad-1e19-46ee-accf-dc460a680710"
          }
        ],
        "clinicalStatus" : {
          "coding" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
              "code" : "active",
              "display" : "Active"
            }
          ]
        },
        "verificationStatus" : {
          "coding" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
              "code" : "confirmed",
              "display" : "Confirmed"
            }
          ]
        },
        "type" : "allergy",
        "category" : [
          "food"
        ],
        "code" : {
          "coding" : [
            {
              "system" : "http://snomed.info/sct",
              "code" : "227493005",
              "display" : "Cashew nuts",
              "userSelected" : true
            }
          ]
        },
        "patient" : {
          "reference" : "https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC7284",
          "type" : "Patient",
          "display" : "Sage Westbrook"
        },
        "recorder" : {
          "reference" : "https://api.hip.digital.health.nz/fhir/hpi/v1/Practitioner/91ZZXN",
          "type" : "Practitioner",
          "display" : "DR Julian Subatoi Bashir"
        }
      },
      "search" : {
        "mode" : "match"
      }
    }
  ]
}

This search requests AllergyIntolerance resources for a patient. Because the search matches a confidential resource, that resource is omitted and the server adds a REDACTED tag to Bundle.meta.security. The tag tells the API consumer that the result set has been filtered. For this stored-resource example, Bundle.total reports the number of matches before confidentiality filtering. Medication searches return Bundle.total only for _count=0; otherwise it is omitted. AIR totals follow the immunisation rules linked above.

Read response

GET /AllergyIntolerance/{id}

Response status: 403

Response body:

{
  "resourceType" : "OperationOutcome",
  "id" : "APIError-Confidential",
  "text" : {
    "status" : "generated",
    "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: OperationOutcome APIError-Confidential</b></p><a name=\"APIError-Confidential\"> </a><a name=\"hcAPIError-Confidential\"> </a><h3>Issues</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Severity</b></td><td><b>Code</b></td><td><b>Diagnostics</b></td></tr><tr><td style=\"display: none\">*</td><td>Error</td><td>Security Problem</td><td>Resource access is forbidden</td></tr></table></div>"
  },
  "issue" : [
    {
      "severity" : "error",
      "code" : "security",
      "diagnostics" : "Resource access is forbidden"
    }
  ]
}

In this example, a request for a single confidential resource receives an HTTP 403 response.

Record withheld at source behaviour

The following search supplies these parameters:

GET /Condition?patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC4633&_source=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fhpi%2Fv1%2FLocation%2FF38006-B&identifier=6b8a6cc1-612f-456e-89df-9fbcd753acb2

In this example, the supplied parameters exactly match a single record that the source system has marked as withheld. The server does not hold the clinical record, but it can uniquely match the search to the withheld record registered through the $participate operation.

The search response contains an OperationOutcome entry with "mode":"outcome":

Click to view example response 
{
  "resourceType" : "Bundle",
  "id" : "SearchExactMatchRecordWithheldExample",
  "meta" : {
    "lastUpdated" : "2025-04-29T23:35:29.795Z"
  },
  "type" : "searchset",
  "total" : 0,
  "link" : [
    {
      "relation" : "self",
      "url" : "https://api.mock.sdhr.digital.health.nz/s2s/Condition?patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2Fnhi%2Fv1%2FPatient%2FZKC4633&_source=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2FLocation%2FF38006-B&identifier=6b8a6cc1-612f-456e-89df-9fbcd753acb2"
    }
  ],
  "entry" : [
    {
      "resource" : {
        "resourceType" : "OperationOutcome",
        "id" : "OperationOutcomeRecordsWithheldAtSource",
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><a name=\"OperationOutcome_OperationOutcomeRecordsWithheldAtSource\"> </a><p class=\"res-header-id\"><b>Generated Narrative: OperationOutcome OperationOutcomeRecordsWithheldAtSource</b></p><a name=\"OperationOutcomeRecordsWithheldAtSource\"> </a><a name=\"hcOperationOutcomeRecordsWithheldAtSource\"> </a><h3>Issues</h3><table class=\"grid\"><tr><td style=\"display: none\">-</td><td><b>Severity</b></td><td><b>Code</b></td><td><b>Details</b></td></tr><tr><td style=\"display: none\">*</td><td>Information</td><td>Informational Note</td><td><span title=\"Codes:{https://fhir-ig.digital.health.nz/sdhr/CodeSystem/sdhr-outcome-codes sdhr-records-withheld-at-source}\">Patient has withheld records at source. The operation was successful, but some records were not included in the response due to confidentiality settings.</span></td></tr></table></div>"
        },
        "issue" : [
          {
            "severity" : "information",
            "code" : "informational",
            "details" : {
              "coding" : [
                {
                  "system" : "https://fhir-ig.digital.health.nz/sdhr/CodeSystem/sdhr-outcome-codes",
                  "code" : "sdhr-records-withheld-at-source",
                  "display" : "Records withheld at source"
                }
              ],
              "text" : "Patient has withheld records at source. The operation was successful, but some records were not included in the response due to confidentiality settings."
            }
          }
        ]
      },
      "search" : {
        "mode" : "outcome"
      }
    }
  ]
}

See example details

Internal-only operations

The $hnz-participate, $hnz-domain-participate and $hnz-participation-status operations are restricted to authorised Health NZ internal channels and are not available to external API consumers.