NZ Shared Digital Health Record API
0.4.0 - draft

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

API Docs

API Documentation

The SDHR API is comprised of multiple FHIR resources. This page provides technical guidance for applicaiton developers who wish to integrate their applications with the Shared Digital Health Record APIs

Resource Description
API Capability Statement FHIR API Capability Statement. Developers should review this to understand the available API interactions and request requirements such as the Request-Context header
API Artifacts List of FHIR Artifacts for this API
OpenAPI Specification Machine readable OpenAPI specification for this API

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 Encounter FHIRAPIEncountermethods(GET, POST,PUT)SDHR Observation FHIRAPIObservationmethods(GET, POST,PUT)SDHR AllergyIntoleranceFHIR APIAllergyIntolerancemethods(GET, POST,PUT)AIR Immunization FHIRAPIImmunizationmethods(GET, POST,PUT)Medicine DataRepository FHIR APIMedicationmethods(GET, POST,PUT)Medical Warning SystemFHIR APIAlertmethods(GET, POST,PUT)National Health IndexPatientmethods(GET, POST,PUT)«person»Patients Patients using healthcare servicesLegend  person  system  container  system boundary  New-Capability  Existing-Capability 


API Search Behaviour

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

You can see the supported search parameters for this API in the API Capability Statement

See below for some example search queries.

Search for Conditions by Patient and Source

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

GET /Condition?patient=https://api.hip.digital.health.nz/fhir/Patient/ZKC7284&_source=https://api.hip.digital.health.nz/fhir/Location/F38006-B

Click to view example response
In this example the search returns 2 active conditions for the patient `ZKC7284` that were sourced from the HPI location `F38006-B`

{
    "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%2FLocation%2FF38006-B&patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%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": [
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/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/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/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/Location/F38006-B"
                },
                "id": "635b2a1c-bdd1-4a20-8c2f-6d8348352f6a",
                "resourceType": "Condition"
            }
        },
        {
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://server.url/Condition/c3605e85-6785-4fa9-94a5-6d8015416c53",
            "resource": {
                "identifier": [
                    {
                        "system": "https://standards.digital.health.nz/ns/health-record-key-id",
                        "value": "ef5b3aad-14c2-4904-aa25-7411dcb21327"
                    }
                ],
                "extension": [
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/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/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/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/Location/F38006-B"
                },
                "id": "c3605e85-6785-4fa9-94a5-6d8015416c53",
                "resourceType": "Condition"
            }
        }
    ]
}


Search for Resources by Patient and Identifier

In this API identifier can be used to track source system unique identifiers. This should enable systems such as Patient Management Systems to track the provenance of resources. There is no limit on the number of identifiers that a resource can contain.

Request Condition resources for a specific identifier GET Condition?patient=https://api.hip.digital.health.nz/fhir/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/Patient/ZKC7284&identifier=https://some.local.system/ehr-key%7Cd2ed3bc7-da4a-45b8-ae3f-82176f5c64a4

Click to view example response
In this example the above query returns a single result. Note that in most cases omission of the `patient` would return a single result but to avoid any possiblility of identifier non-uniqueness the `patient` modifier **SHOULD** be used.


{
    "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%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": [
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/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/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/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/Location/F38006-B"
                },
                "id": "72ca633a-23cc-4848-a512-5111750508fb",
                "resourceType": "Condition"
            }
        }
    ]
}


SDHR Resource updates

This section describes the process of SDHR API Consumer system interacting with the SDHR FHIR server to update existing resources.

GET before PUT

To maintain data integrity, API Consumers authorized to make updates to resources must use a "GET before PUT" approach. By always fetching the current state of a resource before attempting an update, you ensure that the modifications reflect the most accurate and recent information, without overwriting updates which may have been made by other API Consumers.

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 SDHR API reflects the FHIR Search parameters which are documented in the Server Capability Statement and well as a direct HTTP GET for a resource.

Case 1: The SDHR Server assigned resource ID is known by the API Consumer:

In this scenario, an HTTP GET for the resource can be made to retrieve the resource: GET /Condition/{serverResourceId}.

Once the update has been made, the resource can be updated in the SDHR Server by using an HTTP PUT to the resource: PUT /Condition/{serverResourceId}

Case 2: The SDHR Server assigned resource ID is unknown by the API Consumer:

In this scenario, a FHIR Search must be used with search parameters available to the API Consumer, as the server resource ID cannot be used for a direct HTTP GET.

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

To improve accuracy in this process, API Consumers who submit or update records may append an identifier known to them to the shared record. This may be a representation or a copy of a local identifier used within the local PMS system. When a local identifier is stored, a FHIR Search using an identifier search parameter can be used to retrieve a record.

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/Location/F38006-B(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 local identifier is not submitted to a resource, the search parameters for each resource must be used, which are documented in the Server Capability Statement. This will return a FHIR Bundle which may contain multiple records which must be handled by the API Consumer.

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/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 Confidential Record API behaviour

When a record is created or updated to be marked as confidential using FHIR Security labels, read or search operations that would return the record will result in no access to the record.

When the data sensitivity tags using the confidentiality system http://terminology.hl7.org/CodeSystem/v3-Confidentiality are be applied to any SDHR resource, by adding the tag in the resource meta.security array, the API will use the follow behaviours when the resources are subject to FHIR API Requests.

The behaviours are valid for resources containing an security label using the http://terminology.hl7.org/CodeSystem/v3-Confidentiality system and R (Restricted) or V (Very Restricted). SDHR resources which do not contain this confidentiality tag will not be 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/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" : "generated",
    "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><a name=\"AllergyIntoleranceExample-en-US\"> </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/Location/F38006-B\">https://api.hip.digital.health.nz/fhir/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: Restricted (Details: Confidentiality code R = 'Restricted')</p></div><p><b>identifier</b>: <code>https://fhir.examplepms.co.nz</code>/ec2d6cad-1e19-46ee-accf-dc460a680710\u00a0(use:\u00a0secondary,\u00a0)</p><p><b>clinicalStatus</b>: <span title=\"Codes:{http://snomed.info/sct 443601000210103}\">Active Phase</span></p><p><b>verificationStatus</b>: <span title=\"Codes:{http://snomed.info/sct 410605003}\">Confirmed present</span></p><p><b>type</b>: Allergy</p><p><b>category</b>: 62014003</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=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&amp;canonical=https://api.hip.digital.health.nz/fhir/Patient/ZKC7284\">Sage Westbrook</a></p><p><b>recorder</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&amp;canonical=https://api.hip.digital.health.nz/fhir/Practitioner/91ZZXN\">DR Julian Subatoi Bashir</a></p></div>"
  },
  "identifier" : [
    {
      "use" : "secondary",
      "system" : "https://fhir.examplepms.co.nz",
      "value" : "ec2d6cad-1e19-46ee-accf-dc460a680710"
    }
  ],
  "clinicalStatus" : {
    "coding" : [
      {
        "system" : "http://snomed.info/sct",
        "code" : "443601000210103",
        "display" : "Active Phase"
      }
    ]
  },
  "verificationStatus" : {
    "coding" : [
      {
        "system" : "http://snomed.info/sct",
        "code" : "410605003",
        "display" : "Confirmed present"
      }
    ]
  },
  "type" : "allergy",
  "category" : [
    "62014003"
  ],
  "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/Patient/ZKC7284",
    "type" : "Patient",
    "display" : "Sage Westbrook"
  },
  "recorder" : {
    "reference" : "https://api.hip.digital.health.nz/fhir/Practitioner/91ZZXN",
    "type" : "Practitioner",
    "display" : "DR Julian Subatoi Bashir"
  }
}

FHIR Search example

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

Response status: 200

Response body:

{
  "resourceType" : "Bundle",
  "id" : "ConfidentialRecordsSearchResponseExample",
  "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%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/Location/F38006-B",
          "profile" : [
            🔗 "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRAllergyIntolerance"
          ]
        },
        "text" : {
          "status" : "generated",
          "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><a name=\"AllergyIntoleranceExample2-en-US\"> </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/Location/F38006-B\">https://api.hip.digital.health.nz/fhir/Location/F38006-B</a></p><p style=\"margin-bottom: 0px\">Profile: <a href=\"StructureDefinition-SDHRAllergyIntolerance.html\">SDHRAllergyIntolerance</a></p></div><p><b>identifier</b>: <code>https://fhir.examplepms.co.nz</code>/ec2d6cad-1e19-46ee-accf-dc460a680710\u00a0(use:\u00a0secondary,\u00a0)</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>: 370540009</p><p><b>code</b>: <span title=\"Codes:{http://snomed.info/sct 227493005}\">Cashew nuts</span></p><p><b>patient</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&amp;canonical=https://api.hip.digital.health.nz/fhir/Patient/ZKC7284\">Sage Westbrook</a></p><p><b>recorder</b>: <a href=\"https://simplifier.net/resolve?scope=fhir.org.nz.ig.base@3.0.0&amp;canonical=https://api.hip.digital.health.nz/fhir/Practitioner/91ZZXN\">DR Julian Subatoi Bashir</a></p></div>"
        },
        "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" : [
          "370540009"
        ],
        "code" : {
          "coding" : [
            {
              "system" : "http://snomed.info/sct",
              "code" : "227493005",
              "display" : "Cashew nuts",
              "userSelected" : true
            }
          ]
        },
        "patient" : {
          "reference" : "https://api.hip.digital.health.nz/fhir/Patient/ZKC7284",
          "type" : "Patient",
          "display" : "Sage Westbrook"
        },
        "recorder" : {
          "reference" : "https://api.hip.digital.health.nz/fhir/Practitioner/91ZZXN",
          "type" : "Practitioner",
          "display" : "DR Julian Subatoi Bashir"
        }
      },
      "search" : {
        "mode" : "match"
      }
    }
  ]
}

In this request example, a request is made to return AllergyIntolerance resources for a patient using FHIR Search. As a confidential resource was matched with this search, the search result set has been redacted due to confidentiality tags on the resource, resulting in the meta.security REDACTED tag being added to the search result Bundle. This indicates to the API Consumer that some portion of the searchset has been filtered due to confidentiality and not included in the content returned. The total within the response reflects the total of resources before filtering occurs.

FHIR read, vread example

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><a name=\"APIError-Confidential-en-US\"> </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 is made to a single resource which contains a confidentiality flag. This returns a 403 error.