Skip to main content

Proxy role changed event

This event notifies subscribers when a patient's proxy role is updated within the Validated Relationship Service (VRS) using Multicast Notification Service (MNS).

 

Overview

This event notifies subscribers when a patient's proxy role is updated within the Validated Relationship Service (VRS) - the national database of relationships.

It is intended for systems that that need to know whenever a new proxy role is updated in the National Proxy Store.

For general guidance on using MNS, refer to the MNS service page.


Event status

This event is currently in production. 


Who should subscribe to this event

Use this event if your system:

  • maintains an up to date local view of proxy role information

Example use case

  • a proxy role is updated within the National Proxy Store (NPS) for a patient and proxy due to an NHS number being invalidated, the subscribed GPIT system must be informed to keep its local record up to date.

This event may not be suitable if:

  • a GPIT system or healthcare worker wishes to be informed about a proxy role deletion.


How this event works

 

This event follows a notification and retrieval pattern:

  1. A proxy role is update within the NPS

  2. An event is published

  3. A notification is sent to subscribed systems

  4. Your system receives the notification

  5. Your system fetches the proxy role

  6. Your system retrieves and applies the latest data

 


Event structure

This event is available in FHIR format. FHIR events can be published by anybody.

FHIR Type Mandatory Cardinality Description
N/A string M 1.1 version of the schema
id GUID M 1..1 GUID - for this event
Source URI M 1..1 The publisher of the event. Not the original service which triggered the change
event-type string M 1..1

The name of the event will always be vrs-proxy-role-changed-1

timestamp timestamp M 1..1 time of the event ISO 8601
subject string M 1..1 NHS number of the patient
versionid string M 1..1 change number from PDS

 

Example FHIR event

{
  "resourceType": "Bundle",
  "id": "1d98d75d-8fed-448d-a023-7615e7b72c8e",
  "type": "history",
  "timestamp": "2020-06-01T13:00:00Z",
  "entry": [
    {
      "fullUrl": "urn:uuid:1d98d75d-8fed-448d-a023-7615e7b72c8e",
      "resource": {
        "resourceType": "Parameters",
        "meta": {
          "profile": [
            "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription-status-r4"
          ]
        },
        "id": "1d98d75d-8fed-448d-a023-7615e7b72c8e",
        "parameter": [
          {
            "name": "subscription",
            "valueReference": {
              "reference": "https://api.service.nhs.uk/multicast-notification-service/subscriptions"
            }
          },
          {
            "name": "status",
            "valueCode": "active"
          },
          {
            "name": "type",
            "valueCode": "event-notification"
          },
          {
            "name": "notification-event",
            "part": [
              {
                "name": "event-number",
                "valueString": "1"
              },
              {
                "name": "timestamp",
                "valueInstant": "2020-06-01T13:00:00Z"
              },
              {
                "name": "focus",
                "valueReference": {
                  "reference": "https://api.service.nhs.uk/validated-relationships/FHIR/R4/Consent/93f563c0-c1b9-49e7-8fe4-830aed401e03"
                }
              }
            ]
          },
          {
            "name": "additional-context",
            "part": [
              {
                "name": "event-type",
                "valueString": "vrs-proxy-role-changed-1"
              },
              {
                "name": "source",
                "valueUri": "uk.nhs.validated-relationships-service"
              },
              {
                "name": "subject",
                "valueReference": {
                  "identifier": {
                    "value": "1234567890"
                  }
                }
              }
            ]
          }
        ]
      },
      "request": {
        "method": "GET",
        "url": "https://api.service.nhs.uk/multicast-notification-service/subscriptions"
      },
      "response": {
        "status": "200"
      }
    }
  ]
}

Event filtering

You can filter the events you want to receive using the criteria field in the subscription payload. You should only subscribe to events you need and must not create filters wider than required.

Available filters

Filter name Filter subscription type Description
patient_ods_code ODS Code The ODS code of the patient to which the update relates
proxy_ods_code ODS Code The ODS code of the proxy to which the update relates

Onboarding

To subscribe to this event, you will need to:

Refer to Subscribe to Multicast Notification Service for further guidance.


Testing

This event is available to test in Path to Live (PTL) environments.


Versioning

This is the only version of this event.


Contact us

For help and support subscribing to this event and to join our developer community, see Help and support building healthcare software.

Last edited: 10 November 2026 3:57 pm