Use Cases: Real-World Applications of NHS PDS API in Digital Health Product Development – Referral & Patient Portals

Patient Identity Resolution and NHS Number Verification for Safer Referral Workflows

The first job of any referral or portal journey is getting the patient’s identity right. The NHS Personal Demographics Service (PDS) FHIR API is the national source of truth for demographics in England, Wales and the Isle of Man, exposing the data items teams depend on—NHS number, legal and preferred names, addresses, date of birth, contact details, related people, the registered GP practice and even nominated pharmacy choices. When a digital product uses PDS to drive identity resolution up front, everything downstream—letters, e-referrals, lab orders, prescriptions, notifications—becomes cleaner, safer and faster.

Identity resolution in PDS-backed flows typically starts with a trace (patient search) using a minimal set of attributes such as surname, date of birth and, where available, postcode. If the NHS number is already known, you can retrieve the patient record directly. The API’s access mode matters here: in restricted (application-restricted) access, you’re limited to single, uniquely matched patients and read operations; in healthcare worker access, you can return multiple matches to support clinician triage and, where approved, perform certain updates. Designing your referral worklist or intake UI around those contours keeps you compliant while removing ambiguity from match decisions.

Done well, a PDS match should feel invisible to the clinician or patient. In practice, that means your front end should keep the cognitive load low: do not surface systems-level confidence indicators as UX gimmicks (for example, “matching level” values are not designed for end-user consumption), and present candidates strictly in the order returned by PDS. If a record is flagged as sensitive, you must avoid exposing that flag in search results; instead, guide the user to select based on the demographic data and then apply appropriate downstream warnings and controls after selection. These behaviours are not nice-to-haves—they’re part of the conformance expectations for healthcare worker access and should be captured in your acceptance criteria.

For referral journeys specifically, resolving identity through PDS before you touch the e-Referral Service (e-RS), order communications or letters defuses a host of failure modes. It prevents duplicated referrals for similarly named patients at the same practice; it ensures that the GP registration shown to the receiving service is current; and it allows your product to reflect accurate, effective addresses when a provider triages urgency by geography. The net effect is fewer “return to sender” moments, fewer back-office phone calls and faster time-to-appointment. It is also a safety intervention: having the right NHS number tied to the right person is a clinically material control that reduces wrong-patient harm.

Practical design patterns for robust PDS matching:

• Front-load simple inputs and progressively reveal complexity. Start with NHS number where possible, with an accessible path for people who don’t know it. Fall back to DOB + surname + postcode, then widen cautiously for edge cases.
• Never let the user “game” a match. Do not expose internal match scores, and don’t re-order results for convenience; keep result ordering and selection mechanics faithful to the API.
• Fail safe on ambiguity. When a search does not yield a unique match in restricted access, require additional details rather than letting users proceed on a best guess.
• Cache sparingly and validate often. If you keep a local index for performance, treat PDS as the source of truth and re-verify key fields (NHS number, GP practice) at decision points like referral creation or sign-off.

Referral Management: Cleaner Data, Fewer Delays and Better Handover with PDS

Once identity is solid, the PDS record becomes a living dependency for referral management. Most delays in referral admin are not about clinical decisions but about friction: an outdated address means letters bounce; the wrong GP practice means results and advice are sent to the wrong inbox; a stale phone number means the booking team cannot confirm an appointment. By resolving demographics from PDS at the moment you create or update a referral, and again at key status changes, your product eliminates many of these avoidable stalls. Because PDS is national and patient-centred, it smooths handovers across organisations—especially important when patients move across ICS boundaries or change GP practice in the middle of a pathway.

The benefits compound when referrals are triaged centrally or by community providers who don’t share a PAS or EPR with the referrer. A PDS-powered “referral header” ensures every downstream system receives the same canonical identity payload. That improves matching rates in target systems, reduces duplicate creation and bolsters analytics quality. For high-volume referral portals that serve multiple providers, this consistency is a multiplier: it keeps back-office teams working on clinical prioritisation rather than detective work on who’s who.

Designing Patient Portals that Read—and Responsibly Update—Contact Details via PDS

Patient portals are where PDS really earns its keep with citizens. When people view their details, update their mobile number or confirm where appointment letters should go, they’re interacting with data that—if captured correctly—will ripple across the referral ecosystem in a good way. With the PDS FHIR API you can present a patient’s contact details pulled from the national record and, in approved scenarios, PATCH updates back to PDS. The rules are strict but sensible: for each combination of communication method and usage (for example, mobile for personal use), there should be only one active and valid datapoint; when a patient supplies a new value, the old one should be explicitly retired so that only the current datapoint remains live. These semantics keep communications unambiguous and prevent accidental “fan-out” to multiple addresses or numbers.

In patient-facing flows, authentication and identity assurance levels matter. If you want the person to view their details, a well-designed patient access flow suffices; if you want them to update sensitive fields (like address or primary phone), you’ll need to meet the standards for strong authentication and verification—typically via NHS login at a high vector of trust and compliance with DCB3051. On the clinician side, healthcare worker access allows you to present contact details in plain text and, where permitted, update them directly. Unattended services, operating in restricted access, should be especially cautious about modifying contact details and, in many cases, will be reviewed case by case before such changes are allowed. These governance patterns protect patients from accidental disclosure and prevent correspondence going astray.

From a UX perspective, treat contact details as business-effective snapshots. PDS supports “from” and “to” dates that define when an address or telecom is in force; your UI should label historic or invalid datapoints clearly and avoid showing stale values to patients as if they’re current. Where you rely on temporary addresses (for example, a term-time accommodation), consider a policy that nudges the user to reconfirm if the effective window has lapsed—particularly important for outpatient referrals with long waiting times.

There’s also an often-overlooked gem for medicines and appointments journeys: nominated pharmacy. PDS can hold up to three nominations (community pharmacy, appliance contractor and dispensing doctor), each stored as an extension on the Patient resource. Surfacing the nomination in your portal helps patients and services reduce prescription and communication errors—especially when combined with EPS or repeat medication workflows. If your product triggers letters, SMS reminders or sends appointment preparation packs, aligning those with the current nominated pharmacy and preferred contact channel can cut phone-tag and improve uptake.

Implementation DOs and DON’Ts for PDS-backed patient portals:

• DO map each telecom and address to its usage/type and enforce “one active & valid per combination”, retiring the previous value on update.
• DO label historic or invalid data clearly and hide it from patient edit screens unless there’s a good reason to show context.
• DO gate write operations behind the appropriate assurance level (for example, NHS login with high verification) and log provenance.
• DON’T duplicate values across multiple usages “just in case”—that defeats PDS data quality rules and leads to misrouted messages.
• DON’T expose internal matching or sensitivity flags in general patient UIs; apply your policy engine behind the scenes.

Managing Sensitivity, Superseded Numbers and Death Status: Risk Controls You Must Build

Real-world demographic data is messy, and your product must anticipate edge cases. PDS exposes a sensitive record concept. In healthcare worker search flows, you must not display the presence of a sensitive flag in the results list; after selection, your UI should warn the user appropriately and restrict onward sharing—especially important if your referral or portal UI can display addresses captured before the sensitivity was applied. If you store PDS data locally, you are expected to keep it synchronised so that sensitive statuses take effect promptly across your platform. Those behaviours are part of the technical conformance expectations for PDS and should be tested in your end-to-end builds.

Another scenario you will encounter is superseded or invalidated NHS numbers. Supersession occurs when a patient’s NHS number changes (for example, data corrections). Your system should handle the “superseded” code and, where a new NHS number is known, you may need to continue using the old number for the current episode while notifying your local back office to reconcile records. If an NHS number is explicitly invalidated, warn users accessing the record that the identifier is no longer valid and treat all clinical and demographic information with caution until local processes complete. These controls are not academic—they stop you accidentally tying referrals, tests or correspondence to the wrong identity.

Finally, death status. PDS maintains a death notification status and a deceasedDateTime that flows into national eventing (NEMS). For referral portals, this has operational consequences: you must prevent new referral creation for deceased patients, handle any open bookings compassionately, and stop outbound notifications destined for the patient. Subscribing to relevant NEMS topics or polling PDS at key workflow transitions ensures your platform responds promptly when the status changes. Even if your product does not consume NEMS directly, build an internal rule that checks PDS death status before triggering communications or updating a care plan; it’s an essential safety net.

Architecture and Onboarding: Access Modes, Security, and Event-Driven Synchronisation

Teams that thrive with PDS don’t treat it as “just another API”—they model their architecture around its access modes, security model and assurance expectations. At a high level there are three complementary patterns to plan for: restricted (application-restricted) access for server-to-server reads on uniquely matched patients; healthcare worker access when a clinician is present, supporting multi-match search and controlled updates; and patient access for citizen-facing self-service. Your product may use more than one, switching context based on user role and feature. Getting this right at design time avoids costly rework and streamlines onboarding, which includes clinical safety artefacts like hazard and risk logs for the access modes you intend to use.

In healthcare worker access, the authentication and authorisation story centres on NHS Care Identity Service 2 (CIS2) and national RBAC. Your calls must carry the correct User Role Profile ID (URPID) for the role the user selected at sign-in, and your UI must enforce role-based constraints—particularly around multi-patient search and updates. These aren’t mere headers; they’re audited controls that underpin your go-live approvals. Build your identity middleware so it can inject the correct role context into PDS calls, and test it rigorously with simulated job roles (for example, receptionist, referral coordinator, consultant) to prove that only appropriately-privileged users can perform sensitive operations.

For restricted access, design around the single-patient constraint and plan sensible fallbacks when a trace yields multiple matches. Many products combine a restricted service for unattended background checks (for example, nightly data hygiene sweeps) with a healthcare worker flow for interactive sessions. This combination gives you performance and resilience without compromising conformance. Where your portal needs to write to PDS—say, to update an address—ensure the transaction runs under a mode that permits updates (either patient access with adequate assurance or healthcare worker access) and keep an immutable audit trail of who changed what, when and why. Those records help both with clinical safety governance and with user trust when people want to see how their data changes over time.

Event-driven synchronisation is the second pillar. While you can poll PDS, a more robust approach is to subscribe to PDS notifications—for example, change of address, change of GP or death notifications—via the National Events Management Service (NEMS). Triggering silent checks or worklist updates when these events land keeps your local cache fresh and reduces the chance of contacting patients at an old number or sending letters to an old address. Where full eventing is out of scope, put periodic re-verification points into your referral and portal workflows (for example, re-check PDS before sending an appointment confirmation, or at status changes like “ready for clinical triage”).

The contact-details standard published alongside PDS is worth baking into your domain model from day one. It defines how to present and update telecoms and addresses, insists on a single active & valid datapoint per usage/type, and explains business-effective dating semantics. Modelling your database and PATCH logic to those rules means your portal UX will align with national expectations, and your correspondence will go to the intended place every time. Because the same standard applies to healthcare worker UIs and unattended services—with different permissions—it also gives you a common language across your front ends and background services.

Lastly, don’t overlook “small” fields with “big” impact. Nominated pharmacy is one: it lives on the Patient as an extension and can hold up to three nominations (community pharmacy, appliance contractor, dispensing doctor). If your referral or portal pathway touches prescriptions, discharge medicines or pharmacy-led services, surfacing and respecting these nominations reduces friction and avoids misroutes. Combined with clear contact preferences, this is the kind of polish that patients notice—and clinicians appreciate—because it shortens the distance between a clinical decision and the thing that needs doing.

Putting it all together

When a referral product and a patient portal both lean on PDS the right way, you get a virtuous cycle:

• The referral front door uses PDS to nail identity, pull the latest GP registration and verify contact routes.
• The patient portal exposes those same demographics back to citizens, who can correct and confirm them—subject to appropriate assurance—so communications actually land.
• Background services listen for PDS/NEMS changes and quietly keep everything in step.
• Healthcare worker UIs respect sensitivity, supersession and invalidation rules, protecting both patients and staff.
• Every significant action is auditable to national standards, smoothing onboarding and incident response.

In other words, PDS isn’t just a box to tick for “demographics”—it’s the foundation on which safe, low-friction referral and portal experiences are built. Anchor your identity flows in it, design your UX to its semantics, and wire your platform to respond to its events. Do that, and your digital health product will waste less time on administrative dead-ends and more time on what matters: getting people the care they need, sooner and more reliably.