Validated GP registration request event
Use this page to view the Validated GP registration request event available via the Multicast Notification Service API (MNS).
You should use this document alongside the Create Subscriptions API documentation when you want to subscribe to this event.
Overview
This event notifies subscribers when a register with a GP surgery has been requested and approved through the Register with a GP surgery API.
It is intended for systems that need to keep local patient records aligned by reacting to updates as they occur:
- Publisher: Register with a GP surgery
- Event name: gpreg-change-gp-req-1
- Delivery mechanism: Multicast Notification Service (MNS)
- Payload type: Notification (events only)
- Data retrieval: Register with a GP surgery API
This event is triggered when a request has been made through the Register with a GP surgery service and has been auto approved/accepted.
When should I use this event
Use this event if your GP system:
- needs to stay aligned with a patient's registered GP surgery
- needs to stay aligned with changes to a patient's registered GP surgery
How this event works
This event follows a notification and retrieval pattern:
-
A patient's GP surgery record is updated in Register with a GP surgery API
-
An event is published
-
A notification is sent to subscribed systems
-
Your system receives the notification
-
Your system calls the Register with a GP surgery API using the notification filters specified
-
Your system retrieves and applies the latest data
Event status
This event is currently in production.
Event structure
This event is available in FHIR format. FHIR events can be published by anybody.
| CloudEvents | FHIR | Type | Mandatory | Cardinality | Description |
|---|---|---|---|---|---|
| specversion | N/A | String | M | 1..1 | Indicates this is a version 1 CloudEvent. Always"1.0" |
| id | id | GUID | M | 1..1 | GUID - for this event |
| source | source | URI | M | 1..1 | The publisher of the event. Not the original service which triggered the change |
| type | event-type | String | M | 1..1 | name of the event, will always be gpreg-change-gp-req-1 |
| time | timestamp | Timestamp | M | 1..1 | Time of the event ISO 8601 |
| subject | subject | String | M | 1..1 | NHS number of the patient |
Event schema
On subscribing to this event, subscribers will receive notification in the following format:
-
FHIR R4 Bundle
Example FHIR event
{
"$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
When subscribing to an event, it is possible to define notification filters; for example, ‘only notify me of events for a specific ODS Code’.
This event can be filtered on:
| Filter name | Filter subscription type | Description |
|---|---|---|
| generalpractitioner | GP Practice ODS | |
| supplierNACS | GP IT Supplier ODS | |
| registrationencountercode | Registration Encounter Code |
Onboarding
To subscribe to this event:
- Complete onboarding to Register with a GP Surgery API - FHIR API (if data retrieval is required)
-
Complete onboarding for MNS as a subscriber
-
Use the Subscription API to create a subscription
-
Configure an endpoint to receive event notifications
Testing
This event is available to test in the Path to Live (PTL) environments.
Versions
gpreg-change-gp-req-1 is the only version of this event.
Last edited: 17 September 2026 12:41 pm