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

## : SDHRParticipateOperation - JSON Representation

Active as of 2025-11-18

Raw json | Download

    {
      "resourceType" : "OperationDefinition",
      "id" : "SDHRParticipateOperation",
      "text" : {
        "status" : "generated",
        "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: OperationDefinition SDHRParticipateOperation</b></p><a name=\"SDHRParticipateOperation\"> </a><a name=\"hcSDHRParticipateOperation\"> </a><p>URL: [base]/$participate</p><h3>Parameters</h3><table class=\"grid\"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Scope</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>patient</td><td/><td>1..1</td><td><a href=\"http://hl7.org/fhir/R4/references.html#Reference\">Reference</a></td><td/><td><div><p>Reference must be an NHI Patient URL with format https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZZZ1111 or ZZZ11AA</p>\n</div></td></tr><tr><td>IN</td><td>participationIndicator</td><td/><td>1..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#boolean\">boolean</a></td><td/><td><div><p>Indicates global participation in the Shared Digital Health Record service (true/false)\nIf false, the patient does not wish to participate in the service and their resources will not be shared.\nThis parameter is mandatory when indicating global participation but is not required when indicating partial participation with withheld records (see <code>resourceType</code> and <code>localResourceId</code> parameters).\nIf an API consumer attempts to POST a record for a patient that has not opted in, the API will return an OperationOutcome with an error message indicating that the patient has not indicated their participation preferences.</p>\n</div></td></tr><tr><td>IN</td><td>resourceType</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#string\">string</a></td><td/><td><div><p>The resource type that is being withheld. Must be a valid FHIR resource type supported by the SDHR service, such as <code>Condition</code>, <code>Observation</code> etc. Note that <code>AllergyIntolerance</code> resources MUST NOT be withheld.\nThis parameter is optional and should only be used to specify the type of resource that is withheld from the Shared Digital Health Record service.\nWhen this paramter is used the request MUST contain a <code>reasonCode</code> parameter and a <code>localResourceId</code> parameter.</p>\n</div></td></tr><tr><td>IN</td><td>facilityId</td><td/><td>1..1</td><td><a href=\"http://hl7.org/fhir/R4/references.html#Reference\">Reference</a></td><td/><td><div><p>The HPI Facility ID of the healthcare provider that is withholding the resource.\nThis parameter is mandatory and must be provided to indicate the healthcare provider that is withholding the resource from the Shared Digital Health Record service.\nThe HPI Facility ID must be a valid HPI Facility ID in the format <code>https://api.hip.digital.health.nz/fhir/hpi/v1/Location/{hpi-facility-id}</code>.</p>\n</div></td></tr><tr><td>IN</td><td>localResourceId</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#string\">string</a></td><td/><td><div><p>The local resource ID that is withheld from the Shared Digital Health Record service.\nThis parameter is optional and should only be used to specify the local ID of the resource that is withheld.\nWhen this paramter is used the request MUST contain a <code>reasonCode</code> parameter and a <code>resourceType</code> parameter.</p>\n</div></td></tr><tr><td>IN</td><td>reasonCode</td><td/><td>0..1</td><td><a href=\"http://hl7.org/fhir/R4/datatypes.html#Coding\">Coding</a></td><td><a href=\"ValueSet-sdhr-participation-reason-valueset.html\">ValueSet for SDHR Participation Reason</a> (Required)</td><td><div><p>The reason code for participation. This <strong>MUST</strong> be provided when the intent is to indicate a withheld record or when releasing a record.\nValid codes include:</p>\n<ul>\n<li><code>sdhr-record-withheld</code>: Records withheld from the patient for privacy or confidentiality reasons.</li>\n<li><code>sdhr-record-released</code>: Record that was previously withheld has been released (is no longer confidential or restricted) to the service by the patient.</li>\n</ul>\n</div></td></tr><tr><td>OUT</td><td>return</td><td/><td>1..1</td><td><a href=\"http://hl7.org/fhir/R4/operationoutcome.html\">OperationOutcome</a></td><td/><td><div><p>The result of the operation.\nThis parameter will contain an OperationOutcome resource indicating the success or failure of the operation.\nIf the operation is successful, the OperationOutcome will contain a success message.\nIf the operation fails, the OperationOutcome will contain an error message indicating the reason for the failure.\nThe OperationOutcome resource will be returned in the response body of the operation request.\nSee the following examples for possible OperationOutcome responses:</p>\n<ul>\n<li><a href=\"./OperationOutcome-OperationOutcomeParticipateInvalidPatient.html\">OperationOutcome for invalid patient reference</a></li>\n<li><a href=\"./OperationOutcome-OperationOutcomeParticipateMissingReason.html\">OperationOutcome for missing reason code</a></li>\n<li><a href=\"./OperationOutcome-OperationOutcomeParticipateSuccess.html\">OperationOutcome for successful participation</a>\nNote that the following <code>OperationOutcome</code> would be returned when an API Consumer attempts to POST a record for a patient that has not provided their participation preferences:</li>\n<li><a href=\"./OperationOutcome-OperationOutcomeParticipatePreferencesNotKnown.html\">OperationOutcome for participation preferences not known</a></li>\n</ul>\n</div></td></tr></table></div>"
      },
      "url" : "https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipateOperation",
      "version" : "1.0.0",
      "name" : "Participate",
      "status" : "active",
      "kind" : "operation",
      "date" : "2025-11-18T19:29:08+00:00",
      "publisher" : "Health New Zealand",
      "contact" : [
        {
          "name" : "Health New Zealand",
          "telecom" : [
            {
              "system" : "url",
              "value" : "https://github.com/tewhatuora"
            }
          ]
        },
        {
          "name" : "HNZ Integration Team",
          "telecom" : [
            {
              "system" : "email",
              "value" : "integration@tewhatuora.govt.nz",
              "use" : "work"
            }
          ]
        }
      ],
      "description" : "This operation allows a patient to choose to participate in the Shared Digital Health Record service.\nThis operation should be used by data providers in the Shared Digital Health Record ecosystem such as Patient Management Systems (PMS) or Electronic Health Record (EHR) systems.\nIt can be used to indicate whether the patient wishes to participate, whether any resources are withheld, and the reason for participation. The scope of this operation is the API consumer - e.g. an HPI Facility where patient data is held.\n\nScenarios where this operation might be used include:\n- A patient has opted in to the Shared Digital Health Record service and appropriate data will be shared from the data holder to the service.\n- A patient chooses not to participate in the Shared Digital Health Record service and informs their healthcare provider of this choice.\n- A patient has one or more confidential records, held at their healthcare provider, that are withheld from the service.\n- A patient has previously withheld records but has now released them to the Shared Digital Health Record service.\n\nFor example payloads that might be used with this operation see:\n- [Parameters resource for total non-participation](./Parameters-ParametersDoNotParticipate.html) : This example shows how to indicate that a patient does not wish to participate in the Shared Digital Health Record service (has opted out).\n- [Parameters resource for participation](./Parameters-ParametersParticipate.html) : This example shows how to indicate that a patient wishes to participate in the Shared Digital Health Record service, where previously opted out (opt-in).\n- [Parameters resource for partial participation with withheld records](./Parameters-ParametersParticipateRecordWithheld.html) : This example shows how to indicate that a patient has some confidential records that are withheld from the Shared Digital Health Record service.\n- [Parameters resource for releasing withheld records](./Parameters-ParametersParticipateRecordReleased.html) : This example shows how to indicate that a patient has previously withheld records but has now released them to the Shared Digital Health Record service.\n\nTo make a request to this operation the API Consumer must POST a `Parameters` payload to the operation URL (e.g. `POST https://api.sdhr.digital.health.nz/s2s/$participate`).\n\nThe operation is idempotent, meaning that multiple requests with the same parameters will have the same effect as a single request.\nThe operation is expected to be called by a healthcare provider on behalf of the patient, and the patient must be identified by their NHI.\nThe operation will return an OperationOutcome resource indicating the result of the operation.",
      "code" : "participate",
      "system" : true,
      "type" : false,
      "instance" : false,
      "parameter" : [
        {
          "name" : "patient",
          "use" : "in",
          "min" : 1,
          "max" : "1",
          "documentation" : "Reference must be an NHI Patient URL with format https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZZZ1111 or ZZZ11AA",
          "type" : "Reference"
        },
        {
          "name" : "participationIndicator",
          "use" : "in",
          "min" : 1,
          "max" : "1",
          "documentation" : "Indicates global participation in the Shared Digital Health Record service (true/false)\nIf false, the patient does not wish to participate in the service and their resources will not be shared.\nThis parameter is mandatory when indicating global participation but is not required when indicating partial participation with withheld records (see `resourceType` and `localResourceId` parameters).\nIf an API consumer attempts to POST a record for a patient that has not opted in, the API will return an OperationOutcome with an error message indicating that the patient has not indicated their participation preferences.",
          "type" : "boolean"
        },
        {
          "name" : "resourceType",
          "use" : "in",
          "min" : 0,
          "max" : "1",
          "documentation" : "The resource type that is being withheld. Must be a valid FHIR resource type supported by the SDHR service, such as `Condition`, `Observation` etc. Note that `AllergyIntolerance` resources MUST NOT be withheld.\n    This parameter is optional and should only be used to specify the type of resource that is withheld from the Shared Digital Health Record service.\n    When this paramter is used the request MUST contain a `reasonCode` parameter and a `localResourceId` parameter.",
          "type" : "string"
        },
        {
          "name" : "facilityId",
          "use" : "in",
          "min" : 1,
          "max" : "1",
          "documentation" : "The HPI Facility ID of the healthcare provider that is withholding the resource.\n    This parameter is mandatory and must be provided to indicate the healthcare provider that is withholding the resource from the Shared Digital Health Record service.\n    The HPI Facility ID must be a valid HPI Facility ID in the format `https://api.hip.digital.health.nz/fhir/hpi/v1/Location/{hpi-facility-id}`.",
          "type" : "Reference"
        },
        {
          "name" : "localResourceId",
          "use" : "in",
          "min" : 0,
          "max" : "1",
          "documentation" : "The local resource ID that is withheld from the Shared Digital Health Record service.\n    This parameter is optional and should only be used to specify the local ID of the resource that is withheld.\n    When this paramter is used the request MUST contain a `reasonCode` parameter and a `resourceType` parameter.",
          "type" : "string"
        },
        {
          "name" : "reasonCode",
          "use" : "in",
          "min" : 0,
          "max" : "1",
          "documentation" : "The reason code for participation. This **MUST** be provided when the intent is to indicate a withheld record or when releasing a record.\nValid codes include:\n- `sdhr-record-withheld`: Records withheld from the patient for privacy or confidentiality reasons.\n- `sdhr-record-released`: Record that was previously withheld has been released (is no longer confidential or restricted) to the service by the patient.",
          "type" : "Coding",
          "binding" : {
            "strength" : "required",
            "valueSet" : "https://fhir-ig.digital.health.nz/sdhr/ValueSet/sdhr-participation-reason-valueset"
          }
        },
        {
          "name" : "return",
          "use" : "out",
          "min" : 1,
          "max" : "1",
          "documentation" : "The result of the operation. \nThis parameter will contain an OperationOutcome resource indicating the success or failure of the operation.\nIf the operation is successful, the OperationOutcome will contain a success message.\nIf the operation fails, the OperationOutcome will contain an error message indicating the reason for the failure.\nThe OperationOutcome resource will be returned in the response body of the operation request.\nSee the following examples for possible OperationOutcome responses:\n- [OperationOutcome for invalid patient reference](./OperationOutcome-OperationOutcomeParticipateInvalidPatient.html)\n- [OperationOutcome for missing reason code](./OperationOutcome-OperationOutcomeParticipateMissingReason.html)\n- [OperationOutcome for successful participation](./OperationOutcome-OperationOutcomeParticipateSuccess.html)\nNote that the following `OperationOutcome` would be returned when an API Consumer attempts to POST a record for a patient that has not provided their participation preferences:\n- [OperationOutcome for participation preferences not known](./OperationOutcome-OperationOutcomeParticipatePreferencesNotKnown.html)",
          "type" : "OperationOutcome"
        }
      ]
    }