Health New Zealand Te Whatu Ora Shared Care FHIR API
0.4.5 - release New Zealand flag

Health New Zealand Te Whatu Ora Shared Care FHIR API - Local Development build (v0.4.5) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Dunedin Hospital Outpatients

The Outpatients Appointments API exposes Hospital Outpatient appointments as FHIR Appointments and other related resources. The API provides a single view of outpatient appointments from multiple appointment scheduling systems used within Health NZ.

This allows an appointment management solution to display appointment information and as functionality to manage the workflow of appointments, including confirming, arriving and departing a patient from their appointment.

Currently, the APIs support integration with the following Hospital Outpatients systems:

  • SIPICS – Te Waipounamu regional Patient Administration System (PAS), including clinic-based appointments as well as other ad hoc and day surgery appointments.
  • Cardiobase – Southern district Cardiology information system for Cardiology procedure appointments.
  • Karisma – Southern district Radiology information system for Radiology procedure appointments.

Some functionality of the API is currently limited based on the underlying appointment booking system:

  • Southern Radiology appointments only support retrieval. Updates (confirm, arrive, depart) are not currently supported.

Additionally, a Patient resource is exposed to provide Patient demographic information held within the Hospital Patient Administration System (PAS). This provides the ability to update a limited set of patient demographics held in the PAS (contact details).

Use Cases

1. Appointment Created or Updated
2. Confirm Appointment
3. Arrive Appointment
4. Depart Appointment
5. Retrieve or Update Te Waipounamu Patient Demographics

Appointment Created Or Updated

An event notification will be sent to subscribers for any new or updated appointments, the details can then be retrieved from the Appointment API.

Appointment Created/UpdatedAppointment Created/UpdatedAppointmentShared CareShared CareNEMSBooking AdministratorBooking AdministratorAppointmentAppointmentShared CareShared CareNEMSNEMSAppointmentAppointmentBooking AdministratorBooking AdministratorAppointmentScheduling SystemAppointmentScheduling SystemShared CareFHIR ServerShared CareFHIR ServerNEMSNEMSAppointmentManagement SystemAppointmentManagement SystemAppointmentShared CareShared CareNEMS[01]Subscribe to appointment-updated event[02]Book appointment[03]Appointment Resource Created/Updated[04]publish appointment-updated event[05]appointment-updated event notification[06]Get Appointment[07]Appointment Resource

Confirm Appointment

Update the Appointment Scheduling System to indicate the Patient has confirmed they can attend the appointment.

Key information:

Element Expected update/information
AppointmentResponse.appointment Appointment.Identifier
AppointmentResponse.participantStatus 'accepted'
POST AppointmentResponse body
{
  "resourceType": "AppointmentResponse",
  "meta": {
    "lastUpdated": "2025-11-11T02:29:24.844Z",
    "versionId" : "2",
    "source": "https://standards.digital.health.nz/ns/hpi-facility-id/F04066-D",
    "tag": [
      {
        "system": "https://hub.services.digital.health.nz/ns/correlation-id",
        "code": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    ],
    "profile": [
      "https://fhir-ig.digital.health.nz/shared-care/StructureDefinition/DHOAppointmentResponse"
    ]
  },
  "appointment": {
    "reference": {
        "identifier" : {
            "system": "urn:orion:pas:appointment:patient-appointment:code",
            "value" : "77350"
        }
    }
  },
  "participantType" : [
    {
      "coding" : [
        {
          "system" : "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
          "code" : "SBJ",
          "display" : "Subject"
        }
      ]
    }
  ],
  "participantStatus": "accepted"
}
Patient Confirms AppointmentPatient Confirms AppointmentAppointmentShared CareShared CareNEMSAppointmentBooking AdministratorBooking AdministratorAppointmentAppointmentShared CareShared CareNEMSNEMSAppointmentAppointmentPatient/AdministratorPatient/AdministratorBooking AdministratorBooking AdministratorAppointmentScheduling SystemAppointmentScheduling SystemShared CareFHIR ServerShared CareFHIR ServerNEMSNEMSAppointmentManagement SystemAppointmentManagement SystemPatient/AdministratorPatient/AdministratorAppointmentShared CareShared CareNEMSAppointment[01]Subscribe to appointment-updated eventalt[Appointment confirmed through Appointment Management System][02]Confirms Appointment[03]POST AppointmentResponse Resource[04]Update Appointment to confirmed[Appointment confirmed through Appointment Scheduling System][05]Confirms Appointment[06]Appointment Resource Updated[07]publish appointment-updated event[08]appointment-updated event notification

Arrive Appointment

Update the Appointment Scheduling System to indicate the patient has arrived for their appointment.

Key information:

Element Expected update/information
Encounter.appointment Appointment.Identifier
Encounter.subject Patient.Identifier
Encounter.status 'arrived'
Encounter.class https://terminology.hl7.org/3.1.0/ValueSet-v3-ActEncounterCode.html AMB
POST Encounter body
{
  "resourceType" : "Encounter",
  "meta" : {
    "versionId" : "1",
    "lastUpdated" : "2025-09-04T09:00:00.000Z",
    "source" : "https://standards.digital.health.nz/ns/hpi-facility-id/F04066-D",
    "profile" : ["https://fhir-ig.digital.health.nz/shared-care/StructureDefinition/DHOEncounterCreate",
    "https://fhir-ig.digital.health.nz/shared-care/StructureDefinition/DHOEncounter"],
    "tag" : [{
      "system" : "https://hub.services.digital.health.nz/ns/correlation-id",
      "code" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }]
  },
  "appointment": [{
      "identifier": {
        "system": "urn:orion:pas:appointment:patient-appointment:code",
        "value": "7330769"
      }
  }],
  "subject": {
    "reference": "Patient/CareyCarrington",
    "display": "Carey Carrington"
  },
  "status": "arrived",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "ambulatory"
  }
}
Patient Arrives for AppointmentPatient Arrives for AppointmentAppointmentShared CareShared CareNEMSAppointmentAdministratorAdministratorAppointmentAppointmentShared CareShared CareNEMSNEMSAppointmentAppointmentPatient/AdministratorPatient/AdministratorAdministratorAdministratorAppointmentScheduling SystemAppointmentScheduling SystemShared CareFHIR ServerShared CareFHIR ServerNEMSNEMSAppointmentManagement SystemAppointmentManagement SystemPatient/AdministratorPatient/AdministratorAppointmentShared CareShared CareNEMSAppointment[01]Subscribe to appointment-updated eventalt[Patent arrived through Appointment Management System][02]Arrives for Appointment[03]POST Encounter Resource (reference to Appointment)[04]Create encounter for AppointmentUpdate appointment status (arrived)[Patent arrived through Appointment Scheduling System][05]Confirms Appointment[06]Appointment Resource Updated[07]Publish appointment-updated event[08]appointment-updated event notification

Depart Appointment

Update the Appointment Scheduling System to indicate the patient has departed from their appointment.

Key information:

Element Expected update/information
Encounter.appointment.identifier Appointment.Identifier
Encounter.subject Patient.Identifier
Encounter.status 'finished'
Encounter.period.start arrival time
Encounter.period.end departure time
PUT Encounter body

{
  "resourceType": "Encounter",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2025-12-08T02:50:58.870Z",
    "source": "https://standards.digital.health.nz/ns/hpi-facility-id/F04066-D",
    "profile": [
      "https://fhir-ig.digital.health.nz/shared-care/StructureDefinition/DHOEncounter"
    ],
    "tag": [
      {
        "system": "https://hub.services.digital.health.nz/ns/correlation-id",
        "code": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    ]
  },
  "subject": {
    "reference": "Patient/CareyCarrington",
    "display": "Carey Carrington"
  },
  "status": "finished",
  "class": {
    "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
    "code": "AMB",
    "display": "Ambulatory"
  }
}
Patient Departs AppointmentPatient Departs AppointmentAppointmentShared CareShared CareNEMSAppointmentAdministratorAdministratorAppointmentAppointmentShared CareShared CareNEMSNEMSAppointmentAppointmentAdministratorAdministratorAdministratorAdministratorAppointmentScheduling SystemAppointmentScheduling SystemShared CareFHIR ServerShared CareFHIR ServerNEMSNEMSAppointmentManagement SystemAppointmentManagement SystemAdministratorAdministratorAppointmentShared CareShared CareNEMSAppointment[01]Subscribe to appointment-updated eventalt[Patient departed through Appointment Management System][02]Departs from Appointment[03]Update Encounter Resource (reference to Appointment)[04]Update encounter for AppointmentUpdate appointment status (fulfilled)[Patient departed through Appointment Scheduling System][05]Departs patient from Appointment[06]Appointment Resource Updated[07]publish appointment-updated event[08]appointment-updated event notification

Retrieve Or Update Te Waipounamu Patient Demographics

Retrieve Patient Demographics from a Patient in the Te Waipounamu regional Patient Administration System.

Update contact details (phone/email) for the patient.

Note: Email address will not be automatically available after an update as a verification process with the patient must occur first. Once validated, the email will appear in the Patient resource.

Key information (for update):

Element Expected update/information
Patient.identifier patient's NHI
Patient.status 'finished'
Patent.telecom.system 'phone'
Patent.telecom.use 'home'
Patent.telecom.value patient's phone number
Patent.telecom.system 'email'
Patent.telecom.use 'home'
Patent.telecom.value patient's email address
Retrieve/update Patient DemographicsRetrieve/update Patient DemographicsPatient Administration SystemPatient Administration SystemAppointment FHIRAppointment FHIRNEMSAppointmentAppointmentAdministratorAdministratorPatient Administration SystemPatient Administration SystemAppointment FHIRAppointment FHIRNEMSNEMSAppointmentAppointmentPatient/AdministratorPatient/AdministratorAdministratorAdministratorPatient Administration System(PAS)Patient Administration System(PAS)Appointment FHIRInterfaceAppointment FHIRInterfaceNEMSNEMSAppointmentManagement SystemAppointmentManagement SystemPatient/AdministratorPatient/AdministratorPatient Administration SystemPatient Administration SystemAppointment FHIRAppointment FHIRNEMSAppointmentAppointment[01]Subscribe to patient-updated eventalt[Patient details updated through Appointment Management System (only contact details supported)][02]Patient details updated(contact details only)[03]Update Patient Resource[04]Update Patient details in PAS[Patient details updated throughAppointment Scheduling System][05]Patient details updated[06]Publish patient-updated event[07]patient-updated event notification[08]Get Patient Resource (by NHI)[09]Retrieve patient demographics[10]Patient demographics[11]Patient Resource