POST [base]/Immunization

Creates a new immunisation event. Performs validation checks before persisting.

Required scope: system/Immunization.c

Request headers:

• UserID (optional) – end-user identifier for audit
• FacilityID (optional) – facility where vaccination took place
• SourceSystemID (optional) – source system identifier (HIP Integration Application list)
• X-Correlation-ID (optional) – correlation UUID for tracing
• x-api-key (required) – API Gateway key
• Api-Version (optional, default=1) – API version selector (1 or 2)

Responses:

• 201 Created – immunisation record created; Location and ETag headers returned
• 422 Unprocessable Entity – validation failed (OperationOutcome)
• 403 Forbidden – insufficient scope
• 429 Too Many Requests – rate limit exceeded
• 500 Internal Server Error

GET [base]/Immunization/{ID}

Reads a single immunisation event by its ImmSoT logical ID. Returns the enriched Immunization bundle including Patient, Organization, Practitioner and Location resources when available.

Required scope: system/Immunization.r

Responses:

• 200 OK – Immunization resource (OrchestrationImmunizationBundle)
• 400 Bad Request
• 403 Forbidden
• 404 Not Found
• 429 Too Many Requests
• 500 Internal Server Error

PUT [base]/Immunization/{ID}

Updates an existing immunisation event. Performs validation and optimistic concurrency check via the If-Match header (required, must contain the current versionId ETag).

Required scope: system/Immunization.u or air-admin/Immunization.u

Request headers (additional to standard):

• If-Match (required) – current versionId ETag, e.g. "3"

To suppress data-quality re-evaluation for a known-good update, include in the request body meta.extension the dqIgnore: true flag (see UpdateDQIgnore example).

Responses:

• 200 OK – updated Immunization resource; data-quality results in meta
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 422 Unprocessable Entity – validation failure
• 500 Internal Server Error

GET [base]/Immunization/{ID}/_history

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 meta.extension.

Required scope: system/Immunization.r or air-admin/Immunization.r

Responses:

• 200 OK – Bundle (type=history)
• 400 Bad Request
• 403 Forbidden
• 429 Too Many Requests
• 500 Internal Server Error

POST [base]/Immunization/_search

Searches for immunisation events. Supports two search modes:

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.

Data-quality admin search – requires _query=data-quality, _lastUpdated (range or exact), _offset, _count. Restricted to air-admin/Immunization.s scope.

The request body should be application/x-www-form-urlencoded (not JSON). Both query parameters and form-body parameters are supported.

Required scope: system/Immunization.s or air-admin/Immunization.s

Responses:

• 200 OK – Bundle (type=searchset); total=0 when no records found
• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 429 Too Many Requests
• 500 Internal Server Error

GET [base]/Patient/{NHI}

Reads the current state of an ImmSoT consumer (returned as a FHIR Patient conforming to AIRPatient).

When the optional origin-nhi-version request header is supplied, the API compares it against the stored NHI version:

• Same version → return cached data
• Different version → sync with NHI, update ImmSoT, return fresh data

Required scope: system/Patient.r

Responses: 200 OK, 400, 403, 404, 429, 500

GET [base]/CarePlan/$view?nhi={NHI}

Returns the consumer's full immunisation plan as a Bundle containing CarePlan, Immunization, and ImmunizationRecommendation resources.

Required scope: system/CarePlan.s

Responses: 200 OK (CarePlanBundle), 400, 403, 429, 500