Examples

Query - Implementation Details

The API only supports the following query to retrieve any Covid Immunisation resources for a patient from CIR:

GET [BaseURL]/Immunization?subject.identifier=https://standards.digital.health.nz/ns/nhi-id|ZZZ0008

This query will return a FHIR bundle that contains all the individual Immunization resources for a patient. Each resource represents a single immunisation event

Optionally, you can also request that the patient information and location information that CIR holds, are returned using the _include parameter to include resources referenced from any Immunization events for a patient. E.g.:

GET [BaseURL]/Immunization?subject.identifier=https://standards.digital.health.nz/ns/nhi-id|ZZZ0008&_include=Immunization:subject&_include=Immunization:location

Query Parameters

The following query parameters are required to return a patient's Covid Immunisations:

Query Parameter	Type	URL/ValueSet	Description
subject.identifier^*	token	https://standards.digital.health.nz/ns/nhi-id	The NHI of the patient
_include=Immunization:subject	include	n/a	Returns the Immunization subject resource (the patient) in returned searchset bundle
_include=Immunization:location	include	n/a	Returns the Immunization location resource (where the vaccination occured) in returned searchset bundle

^* Required

Responses

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicate success
Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.)
Codes in the 5xx range indicate an internal server error

Code	Description
200	The resource being returned
400	The request was invalid
401	The request did not include an authentication token or the authentication token was expired
403	The client did not have permission to access the requested resource
404	The requested resource was not found
5XX	Unexpected Error

Examples

Example of the current implementation of GET:

GET Immunization ^{(Example json)}

Examples

Below is an example bundle resource returned in response to the query GET [BaseURL]/Immunization?subject.identifier=https://standards.digital.health.nz/ns/nhi-id|ZZZ0016&_include=Immunization:subject&_include=Immunization:location

Note that one result matches the query (the Immunization entry) and there are two resources included (location & patient) due to the _include parameters being used.

{
  "resourceType": "Bundle",
  "id": "123aUniqueIdForThisQuery",
  "meta": {
    "lastUpdated": "2022-01-18T01:43:30Z"
  },
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "https://api.integration.covid19.health.nz/Immunization?subject.identifier=https://standards.digital.health.nz/ns/nhi-id|ZZZ0016&_include=Immunization:subject&_include=Immunization:location"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://api.integration.covid19.health.nz/Patient/0012O00000GpORMQA3",
      "resource": {
        "resourceType": "Patient",
        "id": "0012O00000GpORMQA3",
        "identifier": [
          {
            "system": "https://standards.digital.health.nz/ns/nhi-id",
            "value": "ZZZ0016"
          }
        ],
        "name": [
          {
            "family": "Chalmers",
            "given": [
              "Peter",
              "James"
            ]
          }
        ]
      },
      "search": {
        "mode": "include"
      }
    },
    {
      "fullUrl": "https://api.integration.covid19.health.nz/Location/F12300",
      "resource": {
        "resourceType": "Location",
        "id": "F12300",
        "address": {
          "city": "Lower Hutt",
          "postalCode": "5010",
          "country": "New Zealand",
          "line": [
            "91 Galapagosweg, Building A"
          ]
        }
      },
      "search": {
        "mode": "include"
      }
    },
    {
      "fullUrl": "https://endpointurl/base/Immunization/IA-000047",
      "resource": {
        "resourceType": "Immunization",
        "id": "IA-000047",
        "meta": {
          "profile": [
            "https://standards.digital.health.nz/fhir/StructureDefinition/CIRImmunization"
          ]
        },
        "status": "completed",
        "vaccineCode": {
          "coding": [
            {
              "system": "http://hl7.org/fhir/sid/cvx",
              "code": "208"
            }
          ],
          "text": "COVID-19, mRNA, LNP-S, PF, 30 mcg/0.3 mL dose"
        },
        "patient": {
          "reference": "Patient/0012O00000GpORMQA3",
          "identifier": {
            "system": "https://standards.digital.health.nz/ns/nhi-id",
            "value": "ZZZ0016"
          },
          "display": "Peter James Chalmers"
        },
        "occurrenceDateTime": "2022-02-23",
        "location": {
          "reference": "Location/F12300",
          "display": "Galapagosweg 91, Building A, Lower Hutt 5010, New Zealand"
        },
        "manufacturer": {
          "display": "Pfizer"
        },
        "lotNumber": "abc123",
        "site": {
          "text": "LVL - Left Vastus Llateralis"
        },
        "route": {
          "text": "Intramuscular (IM)",
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v3-RouteOfAdministration",
              "code": "IM"
            }
          ]
        },
        "extension": [
          {
            "url": "https://standards.digital.health.nz/fhir/StructureDefinition/LotNumberVerificationStatus",
            "valueCodeableConcept": {
              "coding": [
                {
                  "code": "Valid Lookup",
                  "system": "https://standards.digital.health.nz/ns/lot-number-verification-status-code",
                  "display": "Valid - Lookup"
                }
              ]
            }
          }
        ]
      },
      "search": {
        "mode": "match",
        "score": 1
      }
    }
  ]
}