Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1)
1.27.0 - release New Zealand

Aotearoa Immunisation Register (AIR) FHIR Implementation Guide (API-V1) - Local Development build (v1.27.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

## : AIR FHIR Server Capability Statement - JSON Representation

Active as of 2025-06-01

Raw json | Download

    {
      "resourceType" : "CapabilityStatement",
      "id" : "AIRCapabilityStatement",
      "text" : {
        "status" : "extensions",
        "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p class=\"res-header-id\"><b>Generated Narrative: CapabilityStatement AIRCapabilityStatement</b></p><a name=\"AIRCapabilityStatement\"> </a><a name=\"hcAIRCapabilityStatement\"> </a><h2 id=\"title\">AIR FHIR Server Capability Statement</h2><ul><li>Implementation Guide Version: 1.27.0 </li><li>FHIR Version: 4.0.1 </li><li>Supported Formats: <code>json</code>, <code>application/fhir+json</code></li><li>Published on: 2025-06-01 </li><li>Published by: Te Whatu Ora </li></ul><blockquote class=\"impl-note\"><p><strong>Note to Implementers: FHIR Capabilities</strong></p><p>Any FHIR capability may be 'allowed' by the system unless explicitly marked as 'SHALL NOT'. A few items are marked as MAY in the Implementation Guide to highlight their potential relevance to the use case.</p></blockquote><h2 id=\"rest\">FHIR RESTful Capabilities</h2><div class=\"panel panel-default\"><div class=\"panel-heading\"><h3 id=\"mode1\" class=\"panel-title\">Mode: <code>server</code></h3></div><div class=\"panel-body\"><div><p>AIR ImmSoT FHIR R4 server.</p>\n<p>All requests require:</p>\n<ul>\n<li>x-api-key header (API Gateway key)</li>\n<li>OAuth2 bearer token with the appropriate scope (see security schemes)</li>\n<li>Optional: UserID, FacilityID, SourceSystemID, X-Correlation-ID headers for audit</li>\n</ul>\n<p>API version selection is controlled by the Api-Version header (values: 1 or 2, default: 1).</p>\n</div><div class=\"lead\"><em>Security</em></div><div class=\"row\"><div class=\"col-lg-6\">Enable CORS: yes</div><div class=\"col-lg-6\">Security services supported: <code>OAuth</code></div></div><blockquote><div><p>OAuth2 client credentials flow. Obtain a bearer token from the token endpoint then include it as Authorization: Bearer &lt;token&gt;.</p>\n</div></blockquote><div class=\"lead\"><em>Summary of System-wide Interactions</em></div><ul><li>Supports the <code>transaction</code>interaction.</li></ul><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Summary of System-wide Operations</span><table class=\"table table-condensed table-hover\"><thead><tr><th>Conformance</th><th>Operation</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td>$process-message</td><td><div><p><strong>POST</strong> <code>[base]/Immunization/$process-message</code></p>\n<p>Processes an incoming FHIR message Bundle (type=message) to acknowledge a previously sent immunisation update notification. Updates an existing acknowledgement record from status <code>SENT</code> to <code>RECEIVED</code>.</p>\n<p>Request body: FHIR Bundle containing a MessageHeader with <code>response.code=ok</code> and an OperationOutcome entry.</p>\n<p><strong>Required scope:</strong> <code>system/MessageHeader.u</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (OperationOutcome), <code>401</code>, <code>403</code>, <code>422</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr></tbody></table></div></div></div></div><h3 id=\"resourcesCap1\">Capabilities by Resource/Profile</h3><h4 id=\"resourcesSummary1\">Summary</h4><p>The summary table lists the resources that are part of this configuration, and for each resource it lists:</p><ul><li>The relevant profiles (if any)</li><li>The interactions supported by each resource (<b><span class=\"bg-info\">R</span></b>ead, <b><span class=\"bg-info\">S</span></b>earch, <b><span class=\"bg-info\">U</span></b>pdate, and <b><span class=\"bg-info\">C</span></b>reate, are always shown, while <b><span class=\"bg-info\">VR</span></b>ead, <b><span class=\"bg-info\">P</span></b>atch, <b><span class=\"bg-info\">D</span></b>elete, <b><span class=\"bg-info\">H</span></b>istory on <b><span class=\"bg-info\">I</span></b>nstance, or <b><span class=\"bg-info\">H</span></b>istory on <b><span class=\"bg-info\">T</span></b>ype are only present if at least one of the resources has support for them.</li><li><span>The required, recommended, and some optional search parameters (if any). </span></li><li>The linked resources enabled for <code>_include</code></li><li>The other resources enabled for <code>_revinclude</code></li><li>The operations on the resource (if any)</li></ul><div class=\"table-responsive\"><table class=\"table table-condensed table-hover\"><thead><tr><th><b>Resource Type</b></th><th><b>Profile</b></th><th class=\"text-center\"><b title=\"GET a resource (read interaction)\">R</b></th><th class=\"text-center\"><b title=\"GET all set of resources of the type (search interaction)\">S</b></th><th class=\"text-center\"><b title=\"PUT a new resource version (update interaction)\">U</b></th><th class=\"text-center\"><b title=\"POST a new resource (create interaction)\">C</b></th><th class=\"text-center\"><b title=\"GET changes to a resource (history interaction on instance)\">H-I</b></th><th><b title=\"Required and recommended search parameters\">Searches</b></th><th><code><b>_include</b></code></th><th><code><b>_revinclude</b></code></th><th><b>Operations</b></th></tr></thead><tbody><tr><td><a href=\"#Immunization1-1\">Immunization</a></td><td><a href=\"StructureDefinition-air-immunization.html\">https://standards.digital.health.nz/fhir/air/StructureDefinition/air-immunization</a></td><td class=\"text-center\">y</td><td class=\"text-center\">y</td><td class=\"text-center\">y</td><td class=\"text-center\">y</td><td class=\"text-center\">y</td><td>patient, target-disease, status-reason:not-in, status:not-in, status, _query, _lastUpdated, _offset, _count, _includeMigratedData, _dqStatus, _include</td><td><code>*</code>, <code>Immunization:patient</code>, <code>Immunization:performer</code>, <code>Immunization:location</code></td><td/><td><code>$upsert</code>, <code>$bulk-update</code>, <code>$match</code>, <code>$unmatch</code></td></tr><tr><td><a href=\"#Patient1-2\">Patient</a></td><td><a href=\"StructureDefinition-air-patient.html\">https://standards.digital.health.nz/fhir/air/StructureDefinition/air-patient</a></td><td class=\"text-center\">y</td><td class=\"text-center\"/><td class=\"text-center\"/><td class=\"text-center\"/><td class=\"text-center\"/><td/><td/><td/><td><code>$update-state</code>, <code>$reassign-schedules</code>, <code>$patient-history</code></td></tr><tr><td><a href=\"#CarePlan1-3\">CarePlan</a></td><td><a href=\"StructureDefinition-air-careplan.html\">https://standards.digital.health.nz/fhir/air/StructureDefinition/air-careplan</a></td><td class=\"text-center\"/><td class=\"text-center\">y</td><td class=\"text-center\"/><td class=\"text-center\"/><td class=\"text-center\"/><td>nhi</td><td/><td/><td/></tr></tbody></table></div><hr/><div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"Immunization1-1\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: unspecified </span>Immunization</h4></div><div class=\"panel-body\"><div class=\"container\"><div class=\"row\"><div class=\"col-lg-6\"><span class=\"lead\">Base System Profile</span><br/><a href=\"StructureDefinition-air-immunization.html\">AIR Immunization</a></div><div class=\"col-lg-3\"><span class=\"lead\">Profile Conformance</span><br/><b>SHALL</b></div><div class=\"col-lg-3\"><span class=\"lead\">Reference Policy</span><br/><code>logical</code></div></div><p/><div class=\"row\"><div class=\"col-lg-6\"><span class=\"lead\">Interaction summary</span><br/><ul><li>Supports <br/><code>create</code><div><p><strong>POST</strong> <code>[base]/Immunization</code></p>\n<p>Creates a new immunisation event. Performs validation checks before persisting.</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.c</code></p>\n<p><strong>Request headers:</strong></p>\n<ul>\n<li><code>UserID</code> (optional) – end-user identifier for audit</li>\n<li><code>FacilityID</code> (optional) – facility where vaccination took place</li>\n<li><code>SourceSystemID</code> (optional) – source system identifier (HIP Integration Application list)</li>\n<li><code>X-Correlation-ID</code> (optional) – correlation UUID for tracing</li>\n<li><code>x-api-key</code> (required) – API Gateway key</li>\n<li><code>Api-Version</code> (optional, default=1) – API version selector (1 or 2)</li>\n</ul>\n<p><strong>Responses:</strong></p>\n<ul>\n<li><code>201 Created</code> – immunisation record created; Location and ETag headers returned</li>\n<li><code>422 Unprocessable Entity</code> – validation failed (OperationOutcome)</li>\n<li><code>403 Forbidden</code> – insufficient scope</li>\n<li><code>429 Too Many Requests</code> – rate limit exceeded</li>\n<li><code>500 Internal Server Error</code></li>\n</ul>\n</div><code>read</code><div><p><strong>GET</strong> <code>[base]/Immunization/{ID}</code></p>\n<p>Reads a single immunisation event by its ImmSoT logical ID. Returns the enriched Immunization bundle including Patient, Organization, Practitioner and Location resources when available.</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.r</code></p>\n<p><strong>Responses:</strong></p>\n<ul>\n<li><code>200 OK</code> – Immunization resource (OrchestrationImmunizationBundle)</li>\n<li><code>400 Bad Request</code></li>\n<li><code>403 Forbidden</code></li>\n<li><code>404 Not Found</code></li>\n<li><code>429 Too Many Requests</code></li>\n<li><code>500 Internal Server Error</code></li>\n</ul>\n</div><code>update</code><div><p><strong>PUT</strong> <code>[base]/Immunization/{ID}</code></p>\n<p>Updates an existing immunisation event. Performs validation and optimistic concurrency check via the <code>If-Match</code> header (required, must contain the current versionId ETag).</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.u</code> or <code>air-admin/Immunization.u</code></p>\n<p><strong>Request headers (additional to standard):</strong></p>\n<ul>\n<li><code>If-Match</code> (required) – current versionId ETag, e.g. <code>&quot;3&quot;</code></li>\n</ul>\n<p>To suppress data-quality re-evaluation for a known-good update, include in the request body <code>meta.extension</code> the <code>dqIgnore: true</code> flag (see UpdateDQIgnore example).</p>\n<p><strong>Responses:</strong></p>\n<ul>\n<li><code>200 OK</code> – updated Immunization resource; data-quality results in meta</li>\n<li><code>400 Bad Request</code></li>\n<li><code>401 Unauthorized</code></li>\n<li><code>403 Forbidden</code></li>\n<li><code>422 Unprocessable Entity</code> – validation failure</li>\n<li><code>500 Internal Server Error</code></li>\n</ul>\n</div><code>history-instance</code><div><p><strong>GET</strong> <code>[base]/Immunization/{ID}/_history</code></p>\n<p>Returns all versions of an immunisation event as a FHIR history Bundle (type=history). Each bundle entry is a full Immunization resource snapshot at that version, including data-quality metadata in <code>meta.extension</code>.</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.r</code> or <code>air-admin/Immunization.r</code></p>\n<p><strong>Responses:</strong></p>\n<ul>\n<li><code>200 OK</code> – Bundle (type=history)</li>\n<li><code>400 Bad Request</code></li>\n<li><code>403 Forbidden</code></li>\n<li><code>429 Too Many Requests</code></li>\n<li><code>500 Internal Server Error</code></li>\n</ul>\n</div><code>search-type</code><div><p><strong>POST</strong> <code>[base]/Immunization/_search</code></p>\n<p>Searches for immunisation events. Supports two search modes:</p>\n<p><strong>Standard NHI search</strong> – requires <code>patient</code> parameter (NHI number or full Patient reference). Optional filters: <code>target-disease</code>, <code>status-reason:not-in</code>, <code>status:not-in</code>. Include enriched related resources via <code>_include</code>.</p>\n<p><strong>Data-quality admin search</strong> – requires <code>_query=data-quality</code>, <code>_lastUpdated</code> (range or exact), <code>_offset</code>, <code>_count</code>. Restricted to <code>air-admin/Immunization.s</code> scope.</p>\n<p>The request body should be <code>application/x-www-form-urlencoded</code> (not JSON). Both query parameters and form-body parameters are supported.</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.s</code> or <code>air-admin/Immunization.s</code></p>\n<p><strong>Responses:</strong></p>\n<ul>\n<li><code>200 OK</code> – Bundle (type=searchset); total=0 when no records found</li>\n<li><code>400 Bad Request</code></li>\n<li><code>401 Unauthorized</code></li>\n<li><code>403 Forbidden</code></li>\n<li><code>429 Too Many Requests</code></li>\n<li><code>500 Internal Server Error</code></li>\n</ul>\n</div></li></ul></div></div><p/><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Documentation</span><blockquote><div><p>Core immunisation event resource. All interactions operate on FHIR Immunization resources conforming to the AIRImmunization profile.</p>\n</div></blockquote></div></div><div class=\"row\"><div class=\"col-lg-7\"><span class=\"lead\">Search Parameters</span><table class=\"table table-condensed table-hover\"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td>patient</td><td><code>reference</code></td><td><div><p>NHI number of the patient, or a full Patient reference URL.<br/>\nExamples:</p>\n<ul>\n<li><code>patient=ZKN2155</code></li>\n<li><code>patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKN2155</code></li>\n</ul>\n<p>When a full URL is provided it is matched against <code>Immunization.patient.reference</code>.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/immunization.html#search\">target-disease</a></td><td><code>token</code></td><td><div><p>Filter by vaccine-preventable disease (system|code). Comma-separated for multiple values. E.g. <code>http://snomed.info/sct|66071002</code>.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-Immunization-StatusReason.html\">status-reason:not-in</a></td><td><code>token</code></td><td><div><p>Exclude immunisation events with the specified status reason codes. Accepted formats (comma-separated):</p>\n<ul>\n<li><code>system|code</code> e.g. <code>https://standards.digital.health.nz/ns/air-status-reason-terms|CPI</code></li>\n<li><code>|code</code> or bare <code>code</code> for system-independent matching.</li>\n</ul>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"SearchParameter-Immunization-Status.html\">status:not-in</a></td><td><code>token</code></td><td><div><p>Exclude immunisation events with the specified status codes. Allowed values: <code>entered-in-error</code>, <code>completed</code>, <code>not-done</code>.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/immunization.html#search\">status</a></td><td><code>token</code></td><td><div><p>Used in data-quality search only. Include only events with the given status(es). Defaults to all statuses if omitted. Allowed values: <code>entered-in-error</code>, <code>completed</code>, <code>not-done</code>.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_query</td><td><code>special</code></td><td><div><p>Set to <code>data-quality</code> to invoke the admin data-quality search. Requires <code>air-admin/Immunization.s</code> scope. Must be combined with <code>_lastUpdated</code>, <code>_offset</code>, and <code>_count</code>.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"http://hl7.org/fhir/R4/resource.html#search\">_lastUpdated</a></td><td><code>date</code></td><td><div><p>Used in data-quality search. Supports <code>eq</code>, <code>ge</code>, and <code>le</code> prefixes. E.g. <code>ge2023-05-11T00:25:20.641Z</code> or <code>le2023-06-01</code>.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_offset</td><td><code>number</code></td><td><div><p>Used in data-quality search. Number of records to skip. Default: 0.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_count</td><td><code>number</code></td><td><div><p>Used in data-quality search. Maximum records to return (1–100). Default: 100.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_includeMigratedData</td><td><code>string</code></td><td><div><p>Used in data-quality search only. Set to <code>true</code> to include migrated data. Default: <code>false</code>.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_dqStatus</td><td><code>token</code></td><td><div><p>Used in data-quality search only. Filter by data quality status. Allowed values: <code>I</code> (Identified), <code>A</code> (Accepted), <code>P</code> (Passed). Comma-separated.</p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>_include</td><td><code>string</code></td><td><div><p>Include related resources in the response. Supported values: <code>Patient</code>, <code>Immunization:performer</code>, <code>Immunization:location</code>. E.g. <code>_include=Patient</code>.</p>\n</div></td></tr></tbody></table></div><div class=\"col-lg-5\"><span class=\"lead\">Combined Search Parameters</span><table class=\"table table-condensed table-hover\"><thead><tr><th>Conformance</th><th>Parameters</th><th>Types</th></tr></thead><tbody><tr><td>\u00a0</td><td>patient</td><td><code>reference</code></td></tr><tr><td>\u00a0</td><td>patient(+<a href=\"http://hl7.org/fhir/R4/immunization.html#search\">target-disease</a>+<a href=\"SearchParameter-Immunization-StatusReason.html\">status-reason:not-in</a>+<a href=\"SearchParameter-Immunization-Status.html\">status:not-in</a>+_include)</td><td><code>reference</code>(+<code>token</code>+<code>token</code>+<code>token</code>+<code>string</code>)</td></tr><tr><td>\u00a0</td><td>_query+<a href=\"http://hl7.org/fhir/R4/resource.html#search\">_lastUpdated</a>+_offset+_count(+_includeMigratedData+_dqStatus+<a href=\"http://hl7.org/fhir/R4/immunization.html#search\">status</a>)</td><td><code>special</code>+<code>date</code>+<code>number</code>+<code>number</code>(+<code>string</code>+<code>token</code>+<code>token</code>)</td></tr></tbody></table></div></div><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Extended Operations</span><table class=\"table table-condensed table-hover\"><thead><tr><th>Conformance</th><th>Operation</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href=\"OperationDefinition-Immunization-upsert.html\">$upsert</a></td><td><div><p><strong>POST</strong> <code>[base]/Immunization/$upsert</code></p>\n<p>Performs an upsert using a deterministic matching algorithm (NHI + occurrence date + vaccine code + indication):</p>\n<ol>\n<li>No match → create new event</li>\n<li>Single match → update the matched event</li>\n<li>Multiple matches → create new event (duplicate DQ violation raised)</li>\n<li>Processing failure → reject the request</li>\n</ol>\n<p><strong>Required scope:</strong> <code>system/Immunization.c</code> + <code>system/Immunization.u</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (updated) or <code>201 Created</code> (inserted), <code>400</code>, <code>403</code>, <code>422</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"OperationDefinition-Immunization-bulk-update.html\">$bulk-update</a></td><td><div><p><strong>POST</strong> <code>[base]/Immunization/$bulk-update</code></p>\n<p>Atomic bulk create/upsert of immunisation events. Request body is a FHIR Parameters resource (<code>application/x-www-form-urlencoded</code>).</p>\n<p>Each parameter entry has name <code>create</code> or <code>upsert</code> with a contained Immunization resource:</p>\n<ul>\n<li><code>create</code> → always creates a new event</li>\n<li><code>upsert</code> → applies the same matching algorithm as <code>$upsert</code></li>\n</ul>\n<p>The entire operation is atomic: if any event fails, the whole request is rejected.</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.c</code> + <code>system/Immunization.u</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (Parameters resource with <code>created</code>/<code>updated</code> entries), <code>400</code>, <code>403</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>$match</td><td><div><p><strong>POST</strong> <code>[base]/Immunization/{ID}/$match</code></p>\n<p>Manually matches an immunisation event to a planned event in the consumer's vaccination schedule.</p>\n<p>Request body: FHIR Parameters with <code>version</code> (string), <code>plannedEventId</code> (string), and <code>reason.code</code> (string).</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.c</code> + <code>system/Immunization.u</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (Bundle), <code>400</code>, <code>403</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr><tr><td><b>SHALL</b></td><td>$unmatch</td><td><div><p><strong>POST</strong> <code>[base]/Immunization/{ID}/$unmatch</code></p>\n<p>Manually unmatches an immunisation event from a planned event.</p>\n<p>Request body: same structure as <code>$match</code> with an unmatch reason code.</p>\n<p><strong>Required scope:</strong> <code>system/Immunization.c</code> + <code>system/Immunization.u</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (Bundle), <code>400</code>, <code>403</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr></tbody></table></div></div></div></div></div><div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"Patient1-2\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: unspecified </span>Patient</h4></div><div class=\"panel-body\"><div class=\"container\"><div class=\"row\"><div class=\"col-lg-6\"><span class=\"lead\">Base System Profile</span><br/><a href=\"StructureDefinition-air-patient.html\">AIR Patient Profile</a></div><div class=\"col-lg-3\"><span class=\"lead\">Profile Conformance</span><br/><b>SHALL</b></div><div class=\"col-lg-3\"><span class=\"lead\">Reference Policy</span><br/></div></div><p/><div class=\"row\"><div class=\"col-lg-6\"><span class=\"lead\">Interaction summary</span><br/><ul><li>Supports <br/><code>read</code><div><p><strong>GET</strong> <code>[base]/Patient/{NHI}</code></p>\n<p>Reads the current state of an ImmSoT consumer (returned as a FHIR Patient conforming to AIRPatient).</p>\n<p>When the optional <code>origin-nhi-version</code> request header is supplied, the API compares it against the stored NHI version:</p>\n<ul>\n<li>Same version → return cached data</li>\n<li>Different version → sync with NHI, update ImmSoT, return fresh data</li>\n</ul>\n<p><strong>Required scope:</strong> <code>system/Patient.r</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code>, <code>400</code>, <code>403</code>, <code>404</code>, <code>429</code>, <code>500</code></p>\n</div></li></ul></div></div><p/><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Documentation</span><blockquote><div><p>ImmSoT consumer (patient) resource. Stores NHI-linked consumer state, sub-status, and schedule information.</p>\n</div></blockquote></div></div><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Extended Operations</span><table class=\"table table-condensed table-hover\"><thead><tr><th>Conformance</th><th>Operation</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td><a href=\"OperationDefinition-Update-patient-state.html\">$update-state</a></td><td><div><p><strong>POST</strong> <code>[base]/Patient/{NHI}/$update-state</code></p>\n<p>Updates a consumer's state and/or sub-status. Uses optimistic locking: the <code>version</code> parameter must match the server's current version, otherwise a <code>412 Precondition Failed</code> is returned.</p>\n<p>At least one of <code>state</code> or <code>subStatus</code> must be specified. Omitting one leaves it unchanged. Set <code>subStatus</code> to null to clear it.</p>\n<p>Request body: FHIR Parameters with <code>version</code> (integer), optionally <code>state</code> (string), optionally <code>subStatus</code> (string).</p>\n<p><strong>Required scope:</strong> <code>system/Patient.u</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (Patient), <code>400</code>, <code>403</code>, <code>404</code>, <code>412 Precondition Failed</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"OperationDefinition-Reassign-patient-schedules.html\">$reassign-schedules</a></td><td><div><p><strong>POST</strong> <code>[base]/Patient/{NHI}/$reassign-schedules</code></p>\n<p>Reassigns a consumer's immunisation schedules. Cancels existing schedules (including manual matches and MQ records) and creates new ones based on the supplied onboarding date. The schedule repair service is then run to regenerate matches against the new plan.</p>\n<p><strong>Note:</strong> Any manual match linked to a cancelled planned event is also unmatched.</p>\n<p>Request body: FHIR Parameters with <code>reassignDate</code> (date).</p>\n<p><strong>Required scope:</strong> <code>air-admin/Patient.u</code> or <code>system/Patient.u</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (Patient), <code>400</code>, <code>403</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr><tr><td><b>SHALL</b></td><td><a href=\"OperationDefinition-Patient-History.html\">$patient-history</a></td><td><div><p><strong>GET</strong> <code>[base]/Patient/{NHI}/_history</code></p>\n<p>Returns all versions of an ImmSoT consumer as a FHIR history Bundle. Each entry is a full Patient snapshot including modification audit metadata (<code>air-modified-by</code>, <code>air-modified-source-system</code>) in <code>meta.extension</code>.</p>\n<p><strong>Required scope:</strong> <code>air-admin/Patient.r</code> or <code>system/Patient.r</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (Bundle, type=history), <code>400</code>, <code>403</code>, <code>429</code>, <code>500</code></p>\n</div></td></tr></tbody></table></div></div></div></div></div><div class=\"panel panel-default\"><div class=\"panel-heading\"><h4 id=\"CarePlan1-3\" class=\"panel-title\"><span style=\"float: right;\">Resource Conformance: unspecified </span>CarePlan</h4></div><div class=\"panel-body\"><div class=\"container\"><div class=\"row\"><div class=\"col-lg-6\"><span class=\"lead\">Base System Profile</span><br/><a href=\"StructureDefinition-air-careplan.html\">AIR CarePlan Profile</a></div><div class=\"col-lg-3\"><span class=\"lead\">Profile Conformance</span><br/><b>SHALL</b></div><div class=\"col-lg-3\"><span class=\"lead\">Reference Policy</span><br/></div></div><p/><div class=\"row\"><div class=\"col-lg-6\"><span class=\"lead\">Interaction summary</span><br/><ul><li>Supports <br/><code>search-type</code><div><p><strong>GET</strong> <code>[base]/CarePlan/$view?nhi={NHI}</code></p>\n<p>Returns the consumer's full immunisation plan as a Bundle containing CarePlan, Immunization, and ImmunizationRecommendation resources.</p>\n<p><strong>Required scope:</strong> <code>system/CarePlan.s</code></p>\n<p><strong>Responses:</strong> <code>200 OK</code> (CarePlanBundle), <code>400</code>, <code>403</code>, <code>429</code>, <code>500</code></p>\n</div></li></ul></div></div><p/><div class=\"row\"><div class=\"col-12\"><span class=\"lead\">Documentation</span><blockquote><div><p>Read a consumer's immunisation plan (schedule). Each CarePlan represents a single Antigen Group Vaccination (AGV) schedule and links planned ImmunizationRecommendation events and administered Immunization resources.</p>\n</div></blockquote></div></div><div class=\"row\"><div class=\"col-lg-7\"><span class=\"lead\">Search Parameters</span><table class=\"table table-condensed table-hover\"><thead><tr><th>Conformance</th><th>Parameter</th><th>Type</th><th>Documentation</th></tr></thead><tbody><tr><td><b>SHALL</b></td><td>nhi</td><td><code>token</code></td><td><div><p>NHI identifier of the patient/consumer whose immunisation plan to retrieve. Required.</p>\n</div></td></tr></tbody></table></div><div class=\"col-lg-5\">\u00a0</div></div></div></div></div><h2 id=\"messaging\">FHIR Messaging Capabilities</h2><div class=\"panel panel-default\"><div class=\"panel-heading\"><h3 id=\"messaging_1\" class=\"panel-title\">Messaging Capability</h3></div><div class=\"panel-body\"><h4 id=\"msg_sm_1\">Supported Message(s)</h4><table class=\"table table-condensed table-hover\"><thead><tr><th>Mode</th><th>Definition</th></tr></thead><tbody><tr><td>sender</td><td><code>https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationRequestMessageDefinition</code></td></tr><tr><td>sender</td><td><code>https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationResponseMessageDefinition</code></td></tr></tbody></table><span class=\"lead\">Documentation</span><blockquote><div><p>AIR supports HL7 FHIR messaging for immunisation update notifications sent to enrolled consumers and providers.</p>\n</div></blockquote><br/></div></div></div>"
      },
      "url" : "https://standards.digital.health.nz/fhir/air/CapabilityStatement/AIRCapabilityStatement",
      "version" : "1.27.0",
      "name" : "AIRCapabilityStatement",
      "title" : "AIR FHIR Server Capability Statement",
      "status" : "active",
      "experimental" : false,
      "date" : "2025-06-01",
      "publisher" : "Te Whatu Ora",
      "contact" : [
        {
          "name" : "Te Whatu Ora",
          "telecom" : [
            {
              "system" : "url",
              "value" : "https://tewhatuora.govt.nz"
            }
          ]
        }
      ],
      "description" : "The Aotearoa Immunisation Register (AIR) FHIR R4 API (ImmSoT).\n\nAPI versioning:\n- Internal Health NZ consumers call https://air.api.digital.health.nz/fhir/R4.  \n  Omit Api-Version header (or set Api-Version=1) for v1 behaviour; set Api-Version=2 for v2.\n- External consumers call https://api.air.digital.health.nz/s2s/fhir/R4 (v1)  \n  or https://api.air.digital.health.nz/s2s/fhir/R4/v2 (v2).  \n  Both external paths are gateway routes that forward to the internal /fhir/R4 backend.",
      "jurisdiction" : [
        {
          "coding" : [
            {
              "system" : "urn:iso:std:iso:3166",
              "code" : "US",
              "display" : "New Zealand"
            }
          ]
        }
      ],
      "purpose" : "Defines the capabilities of the AIR ImmSoT FHIR server so that clients can discover supported interactions, search parameters, and custom operations.",
      "copyright" : "© 2025 Health New Zealand | Te Whatu Ora",
      "kind" : "instance",
      "implementation" : {
        "description" : "PROD - ImmSoT Service endpoint",
        "url" : "https://air.api.digital.health.nz/fhir/R4"
      },
      "fhirVersion" : "4.0.1",
      "format" : [
        "json",
        "application/fhir+json"
      ],
      "rest" : [
        {
          "mode" : "server",
          "documentation" : "AIR ImmSoT FHIR R4 server.\n\nAll requests require:\n- x-api-key header (API Gateway key)\n- OAuth2 bearer token with the appropriate scope (see security schemes)\n- Optional: UserID, FacilityID, SourceSystemID, X-Correlation-ID headers for audit\n\nAPI version selection is controlled by the Api-Version header (values: 1 or 2, default: 1).",
          "security" : {
            "extension" : [
              {
                "extension" : [
                  {
                    "url" : "token",
                    "valueUri" : "https://auth.integration.covid19.health.nz/oauth2/token"
                  },
                  {
                    "url" : "authorize",
                    "valueUri" : "https://auth.integration.covid19.health.nz/oauth2/authorize"
                  }
                ],
                "url" : "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris"
              }
            ],
            "cors" : true,
            "service" : [
              {
                "coding" : [
                  {
                    "system" : "http://terminology.hl7.org/CodeSystem/restful-security-service",
                    "code" : "OAuth"
                  }
                ]
              }
            ],
            "description" : "OAuth2 client credentials flow. Obtain a bearer token from the token endpoint then include it as Authorization: Bearer <token>."
          },
          "resource" : [
            {
              "extension" : [
                {
                  "extension" : [
                    {
                      "url" : "required",
                      "valueString" : "patient"
                    }
                  ],
                  "url" : "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination"
                },
                {
                  "extension" : [
                    {
                      "url" : "required",
                      "valueString" : "patient"
                    },
                    {
                      "url" : "optional",
                      "valueString" : "target-disease"
                    },
                    {
                      "url" : "optional",
                      "valueString" : "status-reason:not-in"
                    },
                    {
                      "url" : "optional",
                      "valueString" : "status:not-in"
                    },
                    {
                      "url" : "optional",
                      "valueString" : "_include"
                    }
                  ],
                  "url" : "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination"
                },
                {
                  "extension" : [
                    {
                      "url" : "required",
                      "valueString" : "_query"
                    },
                    {
                      "url" : "required",
                      "valueString" : "_lastUpdated"
                    },
                    {
                      "url" : "required",
                      "valueString" : "_offset"
                    },
                    {
                      "url" : "required",
                      "valueString" : "_count"
                    },
                    {
                      "url" : "optional",
                      "valueString" : "_includeMigratedData"
                    },
                    {
                      "url" : "optional",
                      "valueString" : "_dqStatus"
                    },
                    {
                      "url" : "optional",
                      "valueString" : "status"
                    }
                  ],
                  "url" : "http://hl7.org/fhir/StructureDefinition/capabilitystatement-search-parameter-combination"
                }
              ],
              "type" : "Immunization",
              "profile" : "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-immunization",
              "documentation" : "Core immunisation event resource. All interactions operate on FHIR Immunization resources conforming to the AIRImmunization profile.",
              "interaction" : [
                {
                  "code" : "create",
                  "documentation" : "**POST** `[base]/Immunization`\n\nCreates a new immunisation event. Performs validation checks before persisting.\n\n**Required scope:** `system/Immunization.c`\n\n**Request headers:**\n- `UserID` (optional) – end-user identifier for audit\n- `FacilityID` (optional) – facility where vaccination took place\n- `SourceSystemID` (optional) – source system identifier (HIP Integration Application list)\n- `X-Correlation-ID` (optional) – correlation UUID for tracing\n- `x-api-key` (required) – API Gateway key\n- `Api-Version` (optional, default=1) – API version selector (1 or 2)\n\n**Responses:**\n- `201 Created` – immunisation record created; Location and ETag headers returned\n- `422 Unprocessable Entity` – validation failed (OperationOutcome)\n- `403 Forbidden` – insufficient scope\n- `429 Too Many Requests` – rate limit exceeded\n- `500 Internal Server Error`"
                },
                {
                  "code" : "read",
                  "documentation" : "**GET** `[base]/Immunization/{ID}`\n\nReads a single immunisation event by its ImmSoT logical ID. Returns the enriched Immunization bundle including Patient, Organization, Practitioner and Location resources when available.\n\n**Required scope:** `system/Immunization.r`\n\n**Responses:**\n- `200 OK` – Immunization resource (OrchestrationImmunizationBundle)\n- `400 Bad Request`\n- `403 Forbidden`\n- `404 Not Found`\n- `429 Too Many Requests`\n- `500 Internal Server Error`"
                },
                {
                  "code" : "update",
                  "documentation" : "**PUT** `[base]/Immunization/{ID}`\n\nUpdates an existing immunisation event. Performs validation and optimistic concurrency check via the `If-Match` header (required, must contain the current versionId ETag).\n\n**Required scope:** `system/Immunization.u` or `air-admin/Immunization.u`\n\n**Request headers (additional to standard):**\n- `If-Match` (required) – current versionId ETag, e.g. `\"3\"`\n\nTo suppress data-quality re-evaluation for a known-good update, include in the request body `meta.extension` the `dqIgnore: true` flag (see UpdateDQIgnore example).\n\n**Responses:**\n- `200 OK` – updated Immunization resource; data-quality results in meta\n- `400 Bad Request`\n- `401 Unauthorized`\n- `403 Forbidden`\n- `422 Unprocessable Entity` – validation failure\n- `500 Internal Server Error`"
                },
                {
                  "code" : "history-instance",
                  "documentation" : "**GET** `[base]/Immunization/{ID}/_history`\n\nReturns all versions of an immunisation event as a FHIR history Bundle (type=history). Each bundle entry is a full Immunization resource snapshot at that version, including data-quality metadata in `meta.extension`.\n\n**Required scope:** `system/Immunization.r` or `air-admin/Immunization.r`\n\n**Responses:**\n- `200 OK` – Bundle (type=history)\n- `400 Bad Request`\n- `403 Forbidden`\n- `429 Too Many Requests`\n- `500 Internal Server Error`"
                },
                {
                  "code" : "search-type",
                  "documentation" : "**POST** `[base]/Immunization/_search`\n\nSearches for immunisation events. Supports two search modes:\n\n**Standard NHI search** – requires `patient` parameter (NHI number or full Patient reference). Optional filters: `target-disease`, `status-reason:not-in`, `status:not-in`. Include enriched related resources via `_include`.\n\n**Data-quality admin search** – requires `_query=data-quality`, `_lastUpdated` (range or exact), `_offset`, `_count`. Restricted to `air-admin/Immunization.s` scope.\n\nThe request body should be `application/x-www-form-urlencoded` (not JSON). Both query parameters and form-body parameters are supported.\n\n**Required scope:** `system/Immunization.s` or `air-admin/Immunization.s`\n\n**Responses:**\n- `200 OK` – Bundle (type=searchset); total=0 when no records found\n- `400 Bad Request`\n- `401 Unauthorized`\n- `403 Forbidden`\n- `429 Too Many Requests`\n- `500 Internal Server Error`"
                }
              ],
              "versioning" : "versioned",
              "readHistory" : false,
              "updateCreate" : false,
              "conditionalCreate" : false,
              "conditionalRead" : "not-supported",
              "conditionalUpdate" : false,
              "conditionalDelete" : "not-supported",
              "referencePolicy" : [
                "logical"
              ],
              "searchInclude" : [
                "*",
                "Immunization:patient",
                "Immunization:performer",
                "Immunization:location"
              ],
              "searchParam" : [
                {
                  "name" : "patient",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Immunization-patient",
                  "type" : "reference",
                  "documentation" : "NHI number of the patient, or a full Patient reference URL.  \nExamples:\n- `patient=ZKN2155`\n- `patient=https://api.hip.digital.health.nz/fhir/nhi/v1/Patient/ZKN2155`\n\nWhen a full URL is provided it is matched against `Immunization.patient.reference`."
                },
                {
                  "name" : "target-disease",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Immunization-target-disease",
                  "type" : "token",
                  "documentation" : "Filter by vaccine-preventable disease (system|code). Comma-separated for multiple values. E.g. `http://snomed.info/sct|66071002`."
                },
                {
                  "name" : "status-reason:not-in",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Immunization-StatusReason",
                  "type" : "token",
                  "documentation" : "Exclude immunisation events with the specified status reason codes. Accepted formats (comma-separated):\n- `system|code` e.g. `https://standards.digital.health.nz/ns/air-status-reason-terms|CPI`\n- `|code` or bare `code` for system-independent matching."
                },
                {
                  "name" : "status:not-in",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Immunization-Status",
                  "type" : "token",
                  "documentation" : "Exclude immunisation events with the specified status codes. Allowed values: `entered-in-error`, `completed`, `not-done`."
                },
                {
                  "name" : "status",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Immunization-status",
                  "type" : "token",
                  "documentation" : "Used in data-quality search only. Include only events with the given status(es). Defaults to all statuses if omitted. Allowed values: `entered-in-error`, `completed`, `not-done`."
                },
                {
                  "name" : "_query",
                  "definition" : "https://standards.digital.health.nz/fhir/air/SearchParameter/Immunization-data-quality",
                  "type" : "special",
                  "documentation" : "Set to `data-quality` to invoke the admin data-quality search. Requires `air-admin/Immunization.s` scope. Must be combined with `_lastUpdated`, `_offset`, and `_count`."
                },
                {
                  "name" : "_lastUpdated",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Resource-lastUpdated",
                  "type" : "date",
                  "documentation" : "Used in data-quality search. Supports `eq`, `ge`, and `le` prefixes. E.g. `ge2023-05-11T00:25:20.641Z` or `le2023-06-01`."
                },
                {
                  "name" : "_offset",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Resource-offset",
                  "type" : "number",
                  "documentation" : "Used in data-quality search. Number of records to skip. Default: 0."
                },
                {
                  "name" : "_count",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Resource-count",
                  "type" : "number",
                  "documentation" : "Used in data-quality search. Maximum records to return (1–100). Default: 100."
                },
                {
                  "name" : "_includeMigratedData",
                  "definition" : "https://standards.digital.health.nz/fhir/air/SearchParameter/Immunization-includeMigratedData",
                  "type" : "string",
                  "documentation" : "Used in data-quality search only. Set to `true` to include migrated data. Default: `false`."
                },
                {
                  "name" : "_dqStatus",
                  "definition" : "https://standards.digital.health.nz/fhir/air/SearchParameter/Immunization-dqStatus",
                  "type" : "token",
                  "documentation" : "Used in data-quality search only. Filter by data quality status. Allowed values: `I` (Identified), `A` (Accepted), `P` (Passed). Comma-separated."
                },
                {
                  "name" : "_include",
                  "definition" : "http://hl7.org/fhir/SearchParameter/Resource-include",
                  "type" : "string",
                  "documentation" : "Include related resources in the response. Supported values: `Patient`, `Immunization:performer`, `Immunization:location`. E.g. `_include=Patient`."
                }
              ],
              "operation" : [
                {
                  "name" : "upsert",
                  "definition" : "https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-upsert",
                  "documentation" : "**POST** `[base]/Immunization/$upsert`\n\nPerforms an upsert using a deterministic matching algorithm (NHI + occurrence date + vaccine code + indication):\n1. No match → create new event  \n2. Single match → update the matched event  \n3. Multiple matches → create new event (duplicate DQ violation raised)  \n4. Processing failure → reject the request\n\n**Required scope:** `system/Immunization.c` + `system/Immunization.u`\n\n**Responses:** `200 OK` (updated) or `201 Created` (inserted), `400`, `403`, `422`, `429`, `500`"
                },
                {
                  "name" : "bulk-update",
                  "definition" : "https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-bulk-update",
                  "documentation" : "**POST** `[base]/Immunization/$bulk-update`\n\nAtomic bulk create/upsert of immunisation events. Request body is a FHIR Parameters resource (`application/x-www-form-urlencoded`).\n\nEach parameter entry has name `create` or `upsert` with a contained Immunization resource:\n- `create` → always creates a new event\n- `upsert` → applies the same matching algorithm as `$upsert`\n\nThe entire operation is atomic: if any event fails, the whole request is rejected.\n\n**Required scope:** `system/Immunization.c` + `system/Immunization.u`\n\n**Responses:** `200 OK` (Parameters resource with `created`/`updated` entries), `400`, `403`, `429`, `500`"
                },
                {
                  "name" : "match",
                  "definition" : "https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-match",
                  "documentation" : "**POST** `[base]/Immunization/{ID}/$match`\n\nManually matches an immunisation event to a planned event in the consumer's vaccination schedule.\n\nRequest body: FHIR Parameters with `version` (string), `plannedEventId` (string), and `reason.code` (string).\n\n**Required scope:** `system/Immunization.c` + `system/Immunization.u`\n\n**Responses:** `200 OK` (Bundle), `400`, `403`, `429`, `500`"
                },
                {
                  "name" : "unmatch",
                  "definition" : "https://standards.digital.health.nz/fhir/air/OperationDefinition/immunization-unmatch",
                  "documentation" : "**POST** `[base]/Immunization/{ID}/$unmatch`\n\nManually unmatches an immunisation event from a planned event.\n\nRequest body: same structure as `$match` with an unmatch reason code.\n\n**Required scope:** `system/Immunization.c` + `system/Immunization.u`\n\n**Responses:** `200 OK` (Bundle), `400`, `403`, `429`, `500`"
                }
              ]
            },
            {
              "type" : "Patient",
              "profile" : "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-patient",
              "documentation" : "ImmSoT consumer (patient) resource. Stores NHI-linked consumer state, sub-status, and schedule information.",
              "interaction" : [
                {
                  "code" : "read",
                  "documentation" : "**GET** `[base]/Patient/{NHI}`\n\nReads the current state of an ImmSoT consumer (returned as a FHIR Patient conforming to AIRPatient).\n\nWhen the optional `origin-nhi-version` request header is supplied, the API compares it against the stored NHI version:\n- Same version → return cached data  \n- Different version → sync with NHI, update ImmSoT, return fresh data\n\n**Required scope:** `system/Patient.r`\n\n**Responses:** `200 OK`, `400`, `403`, `404`, `429`, `500`"
                }
              ],
              "versioning" : "versioned",
              "readHistory" : false,
              "updateCreate" : false,
              "operation" : [
                {
                  "name" : "update-state",
                  "definition" : "https://standards.digital.health.nz/fhir/air/OperationDefinition/update-patient-state",
                  "documentation" : "**POST** `[base]/Patient/{NHI}/$update-state`\n\nUpdates a consumer's state and/or sub-status. Uses optimistic locking: the `version` parameter must match the server's current version, otherwise a `412 Precondition Failed` is returned.\n\nAt least one of `state` or `subStatus` must be specified. Omitting one leaves it unchanged. Set `subStatus` to null to clear it.\n\nRequest body: FHIR Parameters with `version` (integer), optionally `state` (string), optionally `subStatus` (string).\n\n**Required scope:** `system/Patient.u`\n\n**Responses:** `200 OK` (Patient), `400`, `403`, `404`, `412 Precondition Failed`, `429`, `500`"
                },
                {
                  "name" : "reassign-schedules",
                  "definition" : "https://standards.digital.health.nz/fhir/air/OperationDefinition/reassign-patient-schedules",
                  "documentation" : "**POST** `[base]/Patient/{NHI}/$reassign-schedules`\n\nReassigns a consumer's immunisation schedules. Cancels existing schedules (including manual matches and MQ records) and creates new ones based on the supplied onboarding date. The schedule repair service is then run to regenerate matches against the new plan.\n\n**Note:** Any manual match linked to a cancelled planned event is also unmatched.\n\nRequest body: FHIR Parameters with `reassignDate` (date).\n\n**Required scope:** `air-admin/Patient.u` or `system/Patient.u`\n\n**Responses:** `200 OK` (Patient), `400`, `403`, `429`, `500`"
                },
                {
                  "name" : "patient-history",
                  "definition" : "https://standards.digital.health.nz/fhir/air/OperationDefinition/patient-history",
                  "documentation" : "**GET** `[base]/Patient/{NHI}/_history`\n\nReturns all versions of an ImmSoT consumer as a FHIR history Bundle. Each entry is a full Patient snapshot including modification audit metadata (`air-modified-by`, `air-modified-source-system`) in `meta.extension`.\n\n**Required scope:** `air-admin/Patient.r` or `system/Patient.r`\n\n**Responses:** `200 OK` (Bundle, type=history), `400`, `403`, `429`, `500`"
                }
              ]
            },
            {
              "type" : "CarePlan",
              "profile" : "https://standards.digital.health.nz/fhir/air/StructureDefinition/air-careplan",
              "documentation" : "Read a consumer's immunisation plan (schedule). Each CarePlan represents a single Antigen Group Vaccination (AGV) schedule and links planned ImmunizationRecommendation events and administered Immunization resources.",
              "interaction" : [
                {
                  "code" : "search-type",
                  "documentation" : "**GET** `[base]/CarePlan/$view?nhi={NHI}`\n\nReturns the consumer's full immunisation plan as a Bundle containing CarePlan, Immunization, and ImmunizationRecommendation resources.\n\n**Required scope:** `system/CarePlan.s`\n\n**Responses:** `200 OK` (CarePlanBundle), `400`, `403`, `429`, `500`"
                }
              ],
              "searchParam" : [
                {
                  "name" : "nhi",
                  "definition" : "https://standards.digital.health.nz/fhir/air/SearchParameter/CarePlan-nhi",
                  "type" : "token",
                  "documentation" : "NHI identifier of the patient/consumer whose immunisation plan to retrieve. Required."
                }
              ]
            }
          ],
          "interaction" : [
            {
              "code" : "transaction"
            }
          ],
          "operation" : [
            {
              "name" : "process-message",
              "definition" : "http://hl7.org/fhir/OperationDefinition/MessageHeader-process-message",
              "documentation" : "**POST** `[base]/Immunization/$process-message`\n\nProcesses an incoming FHIR message Bundle (type=message) to acknowledge a previously sent immunisation update notification. Updates an existing acknowledgement record from status `SENT` to `RECEIVED`.\n\nRequest body: FHIR Bundle containing a MessageHeader with `response.code=ok` and an OperationOutcome entry.\n\n**Required scope:** `system/MessageHeader.u`\n\n**Responses:** `200 OK` (OperationOutcome), `401`, `403`, `422`, `429`, `500`"
            }
          ]
        }
      ],
      "messaging" : [
        {
          "documentation" : "AIR supports HL7 FHIR messaging for immunisation update notifications sent to enrolled consumers and providers.",
          "supportedMessage" : [
            {
              "mode" : "sender",
              "definition" : "https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationRequestMessageDefinition"
            },
            {
              "mode" : "sender",
              "definition" : "https://standards.digital.health.nz/fhir/MessageDefinition/UpdateImmunisationResponseMessageDefinition"
            }
          ]
        }
      ]
    }