Personal Demographics Service change event

The PDS record change event notifies subscribers when a patient's record in the Personal Demographics Service (PDS) has been updated.

Overview

The PDS record change event notifies subscribers when a patient's record in the Personal Demographics Service (PDS) has been updated.

This event follows a notification and retrieval pattern. It does not include the updated patient data. Instead, it signals that a change has occurred so that your system can retrieve the latest version of the patient record from PDS.

This approach ensures that PDS remains the source of truth for patient demographics:

publisher: Personal Demographics Service (PDS)
event name: pds-record-change-2
delivery mechanism: Multicast Notification Service (MNS)
payload type: Notification (signal only)
data retrieval: Requires a follow-up call to PDS, which should be the PDS FHIR API for new services onboarding (otherwise legacy systems may use their existing legacy messaging)

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

Event status

This event is currently in private beta.

When should I use this event?

Use this event if your system:

stores local copies of patient demographic data
needs to stay aligned with PDS updates
can retrieve updated data from the PDS API when notified

Example use cases

GP and primary care systems maintaining patient records
administrative systems synchronising demographic data
services managing patient cohorts
systems responding to changes in registration or demographics

How this event works

This event follows a notification and retrieval pattern:

A patient record is created or updated in PDS.
A change event is published.
The event is delivered to a subscribed system via MNS.
Your system receives the event.
Your system retrieves the latest patient record using the NHS number.
Your system applies the latest data.

Event structure

This event is available in both FHIR and CloudEvents formats.

FHIR events are accessible to both internal and external subscribers.
CloudEvents format can be accessed by internal subscribers only.

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 pds-record-change-2
time	timestamp	Timestamp	M	1..1	Time of the event ISO 8601
subject	subject	String	M	1..1	NHS number of the patient
versionid	version-id	String	M	1..1	The NHS Digital assigned version of the patient resource. This is the meta.versionId attribute in a patient resource body in the PDS FHIR API. It may also be referred to as the Serial Change Number (SCN) in older documentation.

Example FHIR event

{
  "resourceType": "Bundle",
  "id": "deb6ed8d-c54a-4489-8609-b15baf927541",
  "type": "history",
  "timestamp": "2020-06-01T13:00:00Z",
  "entry": [
    {
      "fullUrl": "urn:uuid:7c38eb82-9186-402f-a120-94c29ceddb48",
      "resource": {
        "resourceType": "Parameters",
        "meta": {
          "profile": [
            "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription-status-r4"
          ]
        },
        "id": "7c38eb82-9186-402f-a120-94c29ceddb48",
        "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": "additional-context",
            "part": [
              {
                "name": "event-type",
                "valueString": "pds-record-change-2"
              },
              {
                "name": "source",
                "valueUri": "https://fhir.nhs.uk/Id/nhsSpineASID/477121000324"
              },
              {
                "name": "subject",
                "valueReference": {
                  "identifier": {
                    "value": "9912003888"
                  }
                }
              },
              {
                "name": "version-id",
                "valueString": "W/\"4\""
              }
            ]
          }
        ]
      },
      "request": {
        "method": "GET",
        "url": "https://api.service.nhs.uk/multicast-notification-service/subscriptions"
      },
      "response": {
        "status": "200"
      }
    }
  ]
}

CloudEvent example

{
    "specversion": "1.0",
    "id": "236a1d4a-5d69-4fa9-9c7f-e72bf505aa5b",
    "source": "https://fhir.nhs.uk/Id/nhsSpineASID/477121000324",
    "type": "pds-record-change-2",
    "time": "2020-06-01T13:00:00Z",
    "subject": "9912003888",
    "versionid": "2"
}

Subscription filters

You can filter the events you want to receive using the criteria field in the subscription payload. You should only be subscribing to events you need to receive and must not create filters wider than required, for example, subscribing to all patients.

Subscription examples contains some common example use cases.

Negative filters are not supported, for example you cannot set the subscription criteria to "eventType='pds-record-change-2' AND 'changed_address=False'" to receive all changes except address. In the table below the filters which are Boolean should only be set to True.

When a resource is removed from a patient record you will receive an event. When you retrieve the record the resource will not be present. For example, if you filter for changed_name and a temporary name is removed you will receive an event and when you retrieve the record the name resource will no longer contain the temporary name.

If the patient has a confidentiality status of sensitive, you will receive notification of changes to location information, but you will only see the sensitive data if you are permissioned to do so.

Note in all cases the abbreviation gp refers to General Practice and not an individual General Practitioner.

Filter name	PDS FHIR schema name	Description
changed_address	address	Boolean. The address snippet change available in the auditBlob has changed.
changed_birthdate	birthDate	Boolean. The birthtime snippet change available in the auditBlob has changed.
changed_contactpreference	Extension-UKCore-ContactPreference (format/method)	Boolean. The preferredContactMethod snippet has changed.
changed_deathstatus	Extension-UKCore-DeathNotificationStatus	Boolean. A change in the death notification status of the subject.
changed_dispenser	Extension-UKCore-NominatedPharmacy Extension-UKCore-PreferredDispenserOrganization Extension-UKCore-MedicalApplianceSupplier	Boolean. The playedOtherProviderPatient snippet has changed for non-GP types?
changed_gender	gender	Boolean. The gender snippet change available in the auditBlob has changed.
changed_gp_to	generalPractitioner.identifier.value	String. ODS code of new registered GP. The main reason for this is to listen for events where a patient is moving to "your practice", or from one supplier to the other.
changed_gp_to_manufacturer_org	n/a	Expansion from changed_gp_to by MNS platform (naming is original + _manufacturer_org).
changed_name	name	Boolean. The name snippet change available in the auditBlob has changed.
changed_nhscommunication	Extension-UKCore-NHSCommunication (language/interpreter)	Boolean. The language snippet has changed.
changed_nhsnumber	id	Boolean. A new NHS number has been issued for this person in the case of superseded. A PDSretrieval on the original nhsnumber will return the replacement record.
changed_security	meta.security	Boolean. The confidentialityCode snippet(s) change available in the auditBlob has changed. This is for Invalidated and S-flagged records.
changed_telecom	telecom	Boolean. The telecom snippet change available in the auditBlob has changed.
nhsnumber	id	The NHS number. Included for future MNS capabilities to filter by NHS numbers from lookup. In the case of an update for a record being superseded, then this should contain the original NHS number.
registeredgpodscode	generalPractitioner.identifier.value	String, The ODS code of the subject patient's active GP registration, this will return null if no GP registration is active. Note: if there is a change of GP and other changes to notify, then this should be the "losing" GP - the "winning" GP will be taking in the record anyway as part of registration and can be filtered for using the changed_gp_to filter. If only the GP provider is changed or removed the above applies, to allow subscribers to see the change in GP.
registeredgpodscode_manufacturer_org	n/a	Expansion from registeredgpodscodeode by MNS platform (naming is original + _manufacturer_org).

Subscription examples

All the following examples contain the criteria string that forms part of the subscription.

Subscribing to all changes for an individual patient

eventType='pds-record-change-2' AND nhsnumber='<patient NHS number>'

Subscribing to death status changing for an individual patient

eventType='pds-record-change-2' AND nhsnumber='<patient NHS number>' AND changed_deathstatus=True

Patients who have left a specific practice and are no longer registered

eventType='pds-record-change-2' AND changed_gp_to IS NOT NULL AND registeredgpodscode = '<ODS Code of GP practice>'

Subscribing to all changes to patients registered at a GP practice

eventType='pds-record-change-2' AND registeredgpodscode='<ODS Code of GP practice>'

Subscribing to all patients registering or leaving a GP practice

If you do not need to differentiate the event until the patient retrieval to determine if the patient has registered or left the practice, then both events could be delivered on the same stream.

eventType='pds-record-change-2' AND (changed_gp_to='<ODS Code of GP practice>' OR registeredgpopscode='<ODS Code of GP practice>')

Alternatively create two subscriptions:

eventType='pds-record-change-2' AND changed_gp_to='<ODS Code of GP practice>' and eventType='pds-record-change-2' AND registeredgpopscode='<ODS Code of GP practice>'

Then you can distinguish by:

inspecting the event metadata
- SQS delivered events have the message attribute X-MNS-Subscription-ID which will look like {"StringValue": "<subscription_id>", "DataType": "String"}
- MESH delivered events have a subject with the format: <subscription_id>_<event_timestamp>
sending them to different destinations: a "changed to to" queue/mailbox and a "changed gp from" queue/mailbox

Subscribing to all death events to all patients

This subscription should only be used for a legitimate need to be notified of all patients, typically a national system.

eventType='pds-record-change-2' AND changed_deathstatus=True

Onboarding

To subscribe to this event, you will need to:

complete onboarding to PDS FHIR API (if data retrieval is required)
complete onboarding for MNS
use the Subscription API to create a subscription
configure an endpoint to receive event notifications

Refer to Subscribe to Multicast Notification Service for further guidance.

Versioning

pds-record-change-2 is the only version of this event.

This should be used in preference to:

Testing

These events are available in the Path to Live environments (PTL). To test receiving an event, you will need to initiate a change to a demographics record in your test pack that you received when you onboarded to demographics in PTL.

Last edited: 1 May 2026 2:58 pm