Immunisation vaccination record change event
This event notifies subscribers when an immunisation record changes within the Immunisation FHIR API.
The immunisation vaccination record change event is available using the Multicast Notification Service (MNS).
Overview
This event notifies subscribers when an immunisation record changes within the Immunisation FHIR API.
The immunisation vaccination record change event is available using the Multicast Notification Service (MNS).
It is intended for systems that need to keep local patient records aligned by reacting to vaccination updates as they occur.
- Publisher: Vaccinations Data Flow Management
- Event name: imms-vaccination-record-change-1
- Delivery mechanism: Multicast Notification Service
- Payload type: Notification (event only)
- Data retrieval: To be confirmed
For general guidance on using MNS, refer to the MNS service page.
When should I use this event?
Use this event if your system:
- needs to stay aligned with vaccination updates
- stores local copies of vaccination data
Example use cases
-
an individual has received the measles, mumps and rubella (MMR) vaccination and their GP surgery has subscribed to receive notification of the event
- an immunisation record has been updated in error and the GP surgery are notified of the correction
This event may not be suitable if:
- a GP surgery requires updates on multiple patients at once
How this event works
This event follows a notification and retrieval pattern:
- a vaccination record is updated in Vaccinations Data Flow Management
- an event is published
- a notification is sent to the subscribed system
- your system receives the notification
- your system calls the Immunisations FHIR API using the notification filters specified
- your system retrieves and applies the latest data
Event structure
This event is available in both FHIR and CloudEvents formats.
FHIR
- FHIR events are accessible to both internal and external subscribers.
Cloud event
- CloudEvent format can be accessed by internal subscribers only
FHIR R4 example
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "MNS Signal in FHIR R4 Format representation schema",
"type": "object",
"description": "A wrapper object for the MNS Signal, and optionally the hydrated signal",
"properties": {
"resourceType": {
"const": "Bundle"
},
"id": {
"type": "string",
"description": "Event ID",
"examples": [
"236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b"
]
},
"type": {
"const": "history"
},
"timestamp": {
"type": "string",
"description": "ISO-8601 timestamp signifying the time of the occurrence",
"format": "date-time",
"examples": [
"2020-06-01T13:00:00Z"
]
},
"entry": {
"type": "array",
"prefixItems": [
{
"$ref": "#/$defs/mns-fhir-signal"
},
{
"$ref": "#/$defs/hydrated-signal"
}
],
"items": false,
"minItems": 1,
"maxItems": 2
}
},
"required": [
"resourceType",
"id",
"type",
"timestamp",
"entry"
],
"$defs": {
"mns-fhir-signal": {
"type": "object",
"description": "The MNS Signal",
"properties": {
"fullUrl": {
"type": "string",
"description": "A temporary ID for the resource",
"pattern": "^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"examples": [
"urn:uuid:9155bdda-35c9-44d0-a772-37abd7870e5c"
]
},
"resource": {
"type": "object",
"properties": {
"resourceType": {
"const": "Parameters"
},
"meta": {
"type": "object",
"properties": {
"profile": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"const": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription-status-r4"
}
}
},
"required": [
"profile"
]
},
"id": {
"type": "string",
"description": "Temporary ID for resource. Matches fullUrl minus `urn:uuid:`.",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
"examples": [
"9155bdda-35c9-44d0-a772-37abd7870e5c"
]
},
"parameter": {
"type": "array",
"items": false,
"minItems": 5,
"maxItems": 5,
"prefixItems": [
{
"type": "object",
"properties": {
"name": {
"const": "subscription"
},
"valueReference": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"description": "The MNS subscriptions endpoint",
"format": "uri",
"examples": [
"https://api.service.nhs.uk/multicast-notification-service/subscriptions"
]
}
},
"required": [
"reference"
]
}
},
"required": [
"name",
"valueReference"
]
},
{
"type": "object",
"properties": {
"name": {
"const": "status"
},
"valueCode": {
"const": "active"
}
},
"required": [
"name",
"valueCode"
]
},
{
"type": "object",
"properties": {
"name": {
"const": "type"
},
"valueCode": {
"const": "event-notification"
}
},
"required": [
"name",
"valueCode"
]
},
{
"type": "object",
"properties": {
"name": {
"const": "notification-event"
},
"part": {
"type": "array",
"minItems": 2,
"maxItems": 3,
"prefixItems": [
{
"type": "object",
"description": "Note this is a fixed value",
"properties": {
"name": {
"const": "event-number"
},
"valueString": {
"const": "1"
}
},
"required": [
"name",
"valueString"
]
},
{
"type": "object",
"description": "The times of the occurrence",
"properties": {
"name": {
"const": "timestamp"
},
"valueInstant": {
"type": "string",
"format": "date-time",
"examples": [
"2020-06-01T13:00:00Z"
]
}
},
"required": [
"name",
"valueInstant"
]
}
],
"items": {
"type": "object",
"description": "Resource on an API of the publishing service to retrieve full details of the event (or subject record)",
"properties": {
"name": {
"const": "focus"
},
"valueReference": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"format": "uri",
"examples": [
"https://api.service.nhs.uk/register-with-a-gp-surgery/applications/bd468854-4cd5-4e57-9dde-e5a482d50605"
]
}
},
"required": [
"reference"
]
}
},
"required": [
"name",
"valueReference"
]
}
}
},
"required": [
"name",
"part"
]
},
{
"type": "object",
"properties": {
"name": {
"const": "additional-context"
},
"part": {
"type": "array",
"minItems": 2,
"maxItems": 4,
"prefixItems": [
{
"type": "object",
"description": "Describes the occurrence; the name of the event.",
"properties": {
"name": {
"const": "event-type"
},
"valueString": {
"type": "string",
"examples": [
"gpreg-change-gp-req-1"
]
}
},
"required": [
"name",
"valueString"
]
},
{
"type": "object",
"description": "Identifies the producer of the event. This is usually a service, as listed in the [Service Catalogue](https://digital.nhs.uk/services/service-catalogue).",
"properties": {
"name": {
"const": "source"
},
"valueUri": {
"type": "string",
"examples": [
"uk.nhs.register-with-a-gp-surgery-service"
]
}
},
"required": [
"name",
"valueUri"
]
}
],
"items": {
"anyOf": [
{
"type": "object",
"description": "Identifies the subject of the event in the context of the event producer/event type.",
"properties": {
"name": {
"const": "subject"
},
"valueReference": {
"type": "object",
"properties": {
"identifier": {
"type": "object",
"properties": {
"value": {
"type": "string",
"examples": [
"9912003888"
]
}
},
"required": [
"value"
]
}
},
"required": [
"identifier"
]
}
},
"required": [
"name",
"valueReference"
]
},
{
"type": "object",
"description": "Version ID related to the event",
"properties": {
"name": {
"const": "version-id"
},
"valueString": {
"type": "string",
"examples": [
"1"
]
}
},
"required": [
"name",
"valueString"
]
}
]
}
}
},
"required": [
"name",
"part"
]
}
]
},
"request": {
"type": "object",
"properties": {
"method": {
"const": "GET"
},
"url": {
"type": "string",
"format": "uri",
"examples": [
"https://api.service.nhs.uk/multicast-notification-service/subscriptions"
]
}
},
"required": [
"method",
"url"
]
},
"response": {
"type": "object",
"properties": {
"status": {
"const": "200"
}
},
"required": [
"status"
]
}
},
"required": [
"resourceType",
"meta",
"id",
"parameter"
]
}
},
"required": [
"fullUrl",
"resource"
]
},
"hydrated-signal": {
"type": "object",
"description": "For selected event types there is the option to include the hydrated signal alongside the MNS event notification for subscribers who are unable to retrieve the record from the publisher API due to technical constraints.\nThe hydrated signal is a snapshot of the resource at the time of the event, and is as a sibling to the MNS Signal within this wrapper object.\n",
"properties": {
"fullUrl": {
"type": "string",
"format": "uri",
"examples": [
"https://api.service.nhs.uk/register-with-a-gp-surgery/applications/bd468854-4cd5-4e57-9dde-e5a482d50605"
]
},
"resource": {
"type": "object",
"description": "The response from the event publisher's source API, when getting the resource as specified in the event and reflected in the `fullUrl` sibling key."
},
"request": {
"type": "object",
"properties": {
"method": {
"const": "GET"
},
"url": {
"type": "string",
"format": "uri",
"examples": [
"https://api.service.nhs.uk/register-with-a-gp-surgery/applications/bd468854-4cd5-4e57-9dde-e5a482d50605"
]
}
},
"required": [
"method",
"url"
]
},
"response": {
"type": "object",
"properties": {
"status": {
"const": "200"
}
},
"required": [
"status"
]
}
},
"required": [
"fullUrl",
"resource",
"request",
"response"
]
}
}
}
Event filtering
This event can be filtered on:
- GP ODS code (generalpractitioner)
- source organisation (sourceoriganisation)
- event origin (sourceapplication)
- patient age (subjectage)
- immunisation type (immunisationtype)
- action on record (create, update, delete)
When a filter is present it doesn't mean that the data is available in the event - it allows filtering by that value, but the event itself is lightweight and contains no information about the change. To see the changed data, the consumer needs must retrieve the record.
As this event is triggered by a change to a record, filters are only present if that field was changed. This means that filtering on a boolean field being false will never return any results as that filter will not be present.
Onboarding
To subscribe to this event, you will need to:
- complete onboarding to the Immunisation FHIR API
- complete onboarding to MNS as a subscriber
- use the MNS Subscription API to create a subscription
- configure an endpoint to receive event notifications
Refer to Subscribe to Multicast Notification Service for further guidance.
Testing
This event is available to test in the Path To Live (PTL) environment. To test receiving an event you will need to initiate a change to a vaccination record.
Versioning
Imms-vaccination-record-change-1 (latest)
Last edited: 1 May 2026 2:45 pm