NZ Shared Digital Health Record API
0.5.0 - ballot

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

OperationDefinition: SDHRParticipateOperation

Official URL: https://fhir-ig.digital.health.nz/sdhr/OperationDefinition/SDHRParticipateOperation Version: 0.5.0
Active as of 2025-07-03 Computable Name: Participate

This operation allows a patient to choose to participate in the Shared Digital Health Record service. It can be used to indicate whether the patient wishes to participate, whether any resources are withheld, and the reason for participation.

Examples where this operation might be used include:

  • A patient who chooses not to participate in the Shared Digital Health Record service and informs their healthcare provider of this choice.
  • A patient who has some confidential records, held at their healthcare provider, that are withheld from the service.

For example payloads that might be used with this operation see:

To 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).

The operation is idempotent, meaning that multiple requests with the same parameters will have the same effect as a single request. The operation is expected to be called by a healthcare provider on behalf of the patient, and the patient must be identified by their NHI. The operation will return an OperationOutcome resource indicating the result of the operation.

URL: [base]/$$participate

Parameters

UseNameScopeCardinalityTypeBindingDocumentation
INpatient1..1Reference

Reference must be an NHI Patient URL with format https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZZZ1111 or ZZZ11AA

INparticipationIndicator1..1boolean

Indicates participation in the Shared Digital Health Record service (true/false) If false, the patient does not wish to participate in the service and their resources will not be shared. OR The patient has some confidential records that are withheld from the service. The reasonCode parameter must be used to indicate the reason for withholding records or not participating.

INresourceType0..1string

The resource type that is being withheld. Must be a valid FHIR resource type supported by the SDHR service, such as AllergyIntolerance, Condition, etc. 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. This parameter MUST be used when the reasonCode is sdhr-record-withheld to indicate which resources are withheld.

INfacilityId1..1string

The HPI Facility ID of the healthcare provider that is withholding the resource. 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. 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}.

INlocalResourceId0..1string

The local resource ID that is withheld from the Shared Digital Health Record service. This parameter is optional and should only be used to specify the local ID of the resource that is withheld. This parameter MUST be used when the reasonCode is sdhr-record-withheld to indicate which specific resource is withheld.

INreasonCode0..1CodingValueSet for SDHR Participation Reason (Required)

The reason code for participation. This MUST be provided when the participation-indicator is false. It indicates the reason for withholding records or not participating in the Shared Digital Health Record service. Valid codes include:

  • sdhr-record-withheld: Records withheld from the patient for privacy or confidentiality reasons.
  • sdhr-participation: Patient participation preference for the Shared Digital Health Record service. In conjunction with participationIndicator set to false, this indicates that the patient does not wish to participate in the service. If the participationIndicator is true, this code indicates that the patient is participating in the service.
  • sdhr-record-released: Record that was previously withheld has been released (is no longer confidential or restricted) to the service by the patient.
OUTreturn1..1OperationOutcome

The result of the operation. This parameter will contain an OperationOutcome resource indicating the success or failure of the operation. If the operation is successful, the OperationOutcome will contain a success message. If the operation fails, the OperationOutcome will contain an error message indicating the reason for the failure. The OperationOutcome resource will be returned in the response body of the operation request. See the following examples for possible OperationOutcome responses: