Subscribe to a Multicast Notification Service event
How to get approval to subscribe to an event on the to Multicast Notification Service (MNS).
Overview
To create a subscription to an MNS event, you must be approved to access the event by the event publisher.
The publisher will confirm approval to the MNS team. Once confirmed, we will onboard you to the MNS subscriptions API (if this is your first subscription). We will then approve your event access request.
If you already have access to the MNS subscriptions API following approval for a different event, you will not be able to create a subscription for a new event until you have been approved by the publisher.
Once you have been approved and enabled you will need to create a subscription to the event. Creating a subscription will return all of the events of that type.
Tailor your subscription using filters to receive only events relevant to your use case.
Apply to subscribe to an event
Visit the MNS events catalogue to view all events you can subscribe to.
To apply for approval to subscribe to an event you will typically:
- register for the event through our ServiceNow request form selecting the name of the event
- when completing this form you will be asked to:
- confirm your subscription use case
- confirm how you will be filtering your events subscription
- provide your application ID
Create a subscription
When you have access to the event, you can create an MNS subscription for it.
If you do not add filter criteria, the subscription will return all events in the subscription. In most cases, you will add filter criteria to receive only events relevant to your use case.
Once you have created an initial subscription for an event, you can create new subscriptions with different filters OR you can edit an existing filter.
To create a subscription you must post a subscription payload to our /subscribe API.
Subscription delivery
You can specify the endpoint you want events delivered to using the channel.endpoint field in the payload. MNS currently only supports delivery to AWS SQS endpoints and MESH mailboxes. We are working with users during private beta to identify other delivery endpoints. There may be further delivery endpoints available in future.
SQS delivery
Before events can be delivered to your SQS queue, you will need to complete some configuration steps during onboarding e.g. policy and encryption setup. When you make a create subscription request, you must provide your full SQS ARN.
e.g. arn:aws:sqs:eu-west-2:123456789012:queue1
For help and support on creating your SQS queues see our Create and AWS SQS Subscription guide and reach out to us in the developer community.
MESH delivery
If you have already completed MESH onboarding then no further steps will be required aside from calling the subscriptions API. Use a MESH mailbox from their 'Path to Live integration' environment for all non-production MNS environments and a production mailbox for production MNS.
The mailbox ID and workflow ID you require are supplied to the channel.endpoint field in a mesh:// URL scheme.
e.g. mesh://MYMAILBOXOT101?workflow_id=myWorkflow101 specifies the mailbox ID MYMAILBOXOT101 and the workflow ID myWorkflow101.
For help and support on delivery to MESH see our Create a MESH subscription guide and reach out to us in the developer community.
Example subscription (no filter)
{
"resourceType": "Subscription",
"status": "requested",
"end": "2022-04-05T17:31:00.000Z",
"reason": "A good descriptive reason for the subscription, useful in future to help track down subscriber",
"criteria": "eventType='pds-record-change-2'",
"channel": {
"type": "message",
"endpoint": "arn:aws:sqs:eu-west-2:123456789012:queue1",
"payload": "application/fhir+json"
}
}
Include a filter
You can filter the events you want to receive using the criteria field in the payload. As a minimum, you must specify the event type. For example, if you provide eventType=pds-record-change-2 this will mean that you receive all Validated GP Registration Request events. Depending on the event, additional filters are available, for example you can filter by nhsnumber, changed_address, or changed_gp_to for pds-record-change-2 event. We are working with publishers and subscribers during private beta to identify any other useful filters for existing and future event types.
For further information, refer to the examples located within the individual event pages found within our event catalogue and see our Open API Spec.
Example subscription (with filter)
{
"resourceType": "Subscription",
"status": "requested",
"end": "2022-04-05T17:31:00.000Z",
"reason": "A good descriptive reason for the subscription, useful in future to help track down subscriber",
"criteria": "eventType='pds-record-change-2' AND changed_deathstatus=True",
"channel": {
"type": "message",
"endpoint": "arn:aws:sqs:eu-west-2:123456789012:queue1",
"payload": "application/fhir+json"
}
}
Edit a subscription
Following the creation of a subscription, to update the filter you can either create multiple subscriptions with different filters and/or delivery locations, or you can edit your existing subscription.
Delete a subscription
If a subscription is no longer required you can delete your subscription.
View your subscriptions
If you would like to view all of your current subscriptions you are able to get them using our subscription endpoint.
Test your subscription
We provide a test event to allow you to test your subscription before you have access to actual events and to also continually test your connectivity in integration.
This test event is sent every 15 minutes. To access this you must create a subscription using the event name mns-test-signal-1
For more information on the test event see our test event page.
Output schema
The event distributed by MNS to subscribers will follow one of two output formats:
- FHIR R4
- CloudEvent
The CloudEvent format is only available to internal subscribers. All external subscribers will receive events in the standards compliant FHIR R4 format.
Examples of each output format can be found on the MNS test event page.
Below follows the schema definition for each output format.
FHIR R4 schema
{
"$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"
]
}
}
}
CloudEvent schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "MNS Signal in CloudEvents Format representation schema",
"type": "object",
"description": "A CloudEvents-compatible notification envelope for the Multicast Notification Service (MNS). Contains the event envelope fields only; full event details are retrieved via the `dataref` URL.",
"properties": {
"specversion": {
"const": "1.0",
"description": "The version of the CloudEvents specification which the event uses."
},
"id": {
"type": "string",
"description": "Identifies the event. Must be unique within the scope of the producer.",
"minLength": 1,
"examples": [
"236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b"
]
},
"source": {
"type": "string",
"description": "Identifies the producer of the event. Typically a URI reference to the publishing service.",
"minLength": 1,
"format": "uri-reference",
"examples": [
"uk.nhs.personal-demographics-service",
"https://fhir.nhs.uk/Id/nhsSpineASID/477121000324"
]
},
"type": {
"type": "string",
"description": "Describes the occurrence; the name of the event type.",
"minLength": 1,
"examples": [
"pds-change-of-gp-2",
"nhs-number-change-2"
]
},
"time": {
"type": "string",
"description": "Timestamp of when the occurrence happened. Must adhere to RFC 3339.",
"format": "date-time",
"minLength": 1,
"examples": [
"2020-06-01T13:00:00Z"
]
},
"subject": {
"type": "string",
"description": "Describes the subject of the event in the context of the event producer and event type. For patient-related events this is the NHS Number.",
"minLength": 1,
"examples": [
"9912003888"
]
},
"dataref": {
"type": "string",
"description": "A link to an API on the publishing service to retrieve full information about the event or the subject record.",
"format": "uri",
"minLength": 1,
"examples": [
"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9912003888"
]
},
"versionid": {
"type": "string",
"description": "Version identifier for the resource that the event relates to.",
"minLength": 1,
"examples": [
"12"
]
},
},
"required": [
"specversion",
"id",
"source",
"type",
"time"
],
"additionalProperties": false
}
Last edited: 8 May 2026 3:19 pm