NZ Shared Digital Health Record API
1.0.0 - 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.0.0 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 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
Participate Operation | Custom operation designed to capture participation information from API Consumers e.g. Patient Management Systems

## Logical View

## 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/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 2 active conditions for the patient `ZKC7284` that were sourced from the 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%2FF38006-B&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": [
                        {
                            "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": [
                        {
                            "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

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/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 above query returns a single result. Note that in most cases omission of the `patient` would return a single result but to avoid any possibility 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%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": [
                        {
                            "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 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.

### 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.

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.

## SDHR Custom Operations

The SDHR service includes the following FHIR custom operations

### Participate Operation

This operation is designed to enable API Consumers such as PMS systems to notify the SDHR service that a patient has withheld records from the service. To call the operation a `POST` request is made to the base API with a `Parameters` payload. e.g.

    {
      "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",
          "valueCodeableConcept" : {
            "coding" : [
              {
                "system" : "https://fhir-ig.digital.health.nz/sdhr/CodeSystem/sdhr-participation-reason",
                "code" : "sdhr-record-released",
                "display" : "Record released"
              }
            ]
          }
        }
      ]
    }

### Example Participation Flows

\

### Testing the $participate Operation

Most API consumers will have a credential that can be issued a scope that enables them to call the `$participate` operation. API consumers will not have access to the `$hnz-participate` operation so we have set up some NHIs in the UAT environmentto allow you to test outcome handling when a patient has opted out globally via an HNZ channel. ALL requests using these NHIs should fail with a 403 http response and an `OperationOutcome` containing the code `sdhr-participation-status-denied`

NHI | Participate Status
--- | ---
ZMW9001 | Opted out `hnzParticipationIndicator:false`
ZMW9009 | Opted out `hnzParticipationIndicator:false`

## 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/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: Restricted (Details: Confidentiality code R = 'Restricted')</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,\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/nhi/v1/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/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://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/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"
      }
    }

#### FHIR Search example

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

Response status: `200`

Response body:

    {
      "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" : "generated",
              "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><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>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/nhi/v1/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/hpi/v1/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/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"
          }
        }
      ]
    }

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 Search Example Where Matched Records Are Withheld

In the following search the parameters below are supplied

- `patient` | https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKC4633

- `source` | https://api.hip.digital.health.nz/fhir/hpi/v1/Location/FZZ111-A

- `identifier` | 6b8a6cc1-612f-456e-89df-9fbcd753acb2

`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 spplied parameters are an exact match for a singe record that has been indicated as wiithheld by the source system. in this scenario the server does not have the record however it is able to uniquely match to a record that has been withheld using the $participate operation

The search response will contain an `OperationOutcome` with `"mode":"outcome"` as below

    {
      "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

#### 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><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.