Written by Technical Team | Last updated 03.11.2025 | 19 minute read
Getting patient identity right is the quiet backbone of safe, efficient care. Every clinical workflow—from booking and triage to prescribing, discharge, and population health—begins with one deceptively simple step: “Who is this patient?” In England, the canonical source of truth for that answer is the Personal Demographics Service (PDS), which exposes a FHIR-based API for modern systems. Implemented well, PDS integration reduces avoidable harm, eliminates duplicate records, accelerates onboarding, and unlocks cross-organisational care pathways. Implemented poorly, it becomes a point of friction, latency, and risk.
This in-depth guide walks engineering and product teams through what the PDS FHIR API is, how to design a scalable and secure integration around it, and how to navigate identity, privacy, performance, testing and live operations. While the focus is technical, we’ll keep an eye on clinical usability and safety throughout—because identity is a patient safety feature, not just a plumbing concern.
The Personal Demographics Service is the national electronic database of NHS patient details in England. It stores core demographics such as NHS number, names (including preferred names and aliases), date of birth, registered GP practice, address and contact preferences. PDS enables providers to uniquely identify a person and associate them with records across settings—a cornerstone for interoperability and joined-up care. The PDS FHIR API exposes this capability through standard HL7® FHIR® resources and operations so that contemporary applications can search, retrieve, and, in authorised contexts, update patient demographics.
At its simplest, a typical flow looks like this: your clinician-facing app or background service queries PDS using a set of search parameters—commonly a combination of name, date of birth and postcode—or directly by NHS number if known. PDS returns a FHIR Patient resource when it can uniquely match the person, or a set of candidates when more than one plausible match exists. Depending on the access mode you integrate with, the API supports operations to verify an NHS number, read a patient’s record and, where policy allows, write certain demographic updates such as addresses or preferred contact methods. Some modes are “user-restricted”—tied to an authenticated healthcare professional—while others are “application-restricted”, typically for backend services with narrower capabilities.
You’ll see the PDS API referenced inside other national services. For example, GP Connect and Spine Core guidance treat “PDS tracing” as a foundational prerequisite to confirm a person’s NHS number and registered GP before other operations (such as fetching records or sending tasks) can proceed. In other words, PDS is not an optional enhancement; it underpins endpoint discovery, routing, and patient safety checks across the Spine ecosystem.
As you plan your integration, get comfortable with three adjacent services that often accompany PDS: (1) the Care Identity Service 2 (CIS2) for authenticating healthcare workers when you’re using user-restricted APIs; (2) PDS Notifications over the National Event Management Service (NEMS) delivered via MESH, which let you subscribe to demographic events (for example, address changes); and (3) in some niche, batch-oriented scenarios, the Demographics Batch Service for tracing at scale during migrations or reconciliations. Understanding where these fit prevents you from reinventing polling loops and helps you design for eventual consistency.
There is no single “right” diagram for PDS integration; what matters is aligning with your clinical workflows and risk profile. Most providers converge on a layered pattern: a thin, standards-respecting adapter that speaks FHIR to PDS, a domain layer that encapsulates patient identity logic, and a set of clinical applications that consume that identity through a stable internal contract. This separation lets you evolve your internal models or swap out infrastructure without breaking clinical applications.
Begin with an internal patient-identity service that presents a clean interface—something like findPatientByNhsNumber, tracePatientByDemographics, getPatientSummary, subscribeToDemographicsChanges, and recordLinkage. Behind that interface, implement a PDS client responsible for: constructing valid FHIR queries, handling pagination and match outcomes (unique, multiple, none), performing referential integrity checks, and translating PDS response nuances into your domain language. Resist the temptation to scatter direct PDS calls throughout apps; centralising the integration minimises duplicate logic and security exposure.
Caching deserves careful thought. Aggressive caching of demographics improves speed and resilience when PDS is busy, but stale identity can be risky. Consider a two-tier approach: a short-lived in-memory cache for UI responsiveness, and a database cache with clear time-to-live (TTL) and provenance. In clinical workflows, show timestamps and sources (“Verified with PDS 8 minutes ago”) so users can judge freshness. For critical workflows (e.g., prescribing), refresh on-demand or subscribe to notifications for change events. Your cache entries should carry both the FHIR Patient resource as returned and a normalised, versioned internal projection, so downstream services never rely on FHIR shape or extensions directly.
Trace logic is where “simple search” becomes safety-critical. Enforce a deterministic hierarchy of identifiers and attributes. If an NHS number is present and passes checksum, prefer a direct GET/read to confirm the record. If not, do a demographic trace with a strict match policy: normalise names (case, diacritics, common aliases), strip punctuation, standardise postcodes, and consider phonetic encodings for clinician-entered searches; but always treat returned candidates conservatively. Only latch onto a record automatically when the API indicates a unique, high-confidence match. Present multiple candidates to clinicians with clear cues (address, GP practice) and safe defaults (“no auto-linking without confirmation”). This blend of deterministic and human-in-the-loop matching reduces wrong-patient errors.
Finally, mind the broader Spine ecosystem. If you consume GP Connect or other Spine services, build explicit sequencing: PDS trace → confirm NHS number and registered GP’s ODS code → use that ODS in endpoint lookup → call downstream APIs. This avoids hidden couplings and makes error handling simpler when any step fails (e.g., newly registered patients not yet reflected across systems).
Security for PDS is not an afterthought; it is the main act. When your use case involves a person at a screen (clinician, admin, call centre), you will typically integrate with the NHS Care Identity Service 2 (CIS2) and follow the “user-restricted RESTful APIs” pattern. Practically, that means implementing OAuth 2.0 and OpenID Connect flows against the NHS authorisation server, handling the interactive login, and obtaining a token that encodes who the user is, how they authenticated (for example, smartcard, authenticator app, security key), and what they are allowed to do. Your app then presents that token when calling PDS to prove both application and end-user identity.
CIS2 exists because smartcards alone don’t suit every clinical context. Modern authentication options—such as platform authenticators on Windows, security keys, and mobile authenticators—are now available and reduce friction for multidisciplinary teams who move across locations or devices. If you’re replacing a legacy Spine Security Broker (SSB) smartcard integration, the shift to CIS2 brings two benefits: standards-based flows that your identity stack likely already knows, and a better user experience that is still high-assurance. Plan for this change if you are modernising; SSB-based approaches are in managed decline.
Practical security implementation checklist
Strong security is necessary but not sufficient; you must also build data protection in depth. Treat demographics as personal data with heightened sensitivity: implement data minimisation (fetch only what you use), redact fields that are not required for a given workflow, and segregate datasets where different care teams have different legitimate purposes. When you persist PDS data locally—for example, to support offline or reduce latency—record provenance and versioning so that you can meet subject-access requests, right-to-rectification workflows, and audit obligations without guesswork.
Operational access is another security surface. Create break-glass policies for emergency access, with independent logs and retrospective review. Provide administrators with tools to revoke tokens, disable client credentials, and force re-authentication if a device is lost or compromised. Implement alerting for anomalous patterns—like unusually high search volumes by a user or queries outside normal working hours—to catch misuse early without burdening frontline staff.
Identity success rests on your matching strategy. The PDS FHIR API intentionally avoids fuzzy “best guess” responses; it tries to return a unique match or a list of candidates, which keeps the system honest. Your job is to take that signal and apply rules that balance safety and speed for your workflows. The safest primary key remains a validated NHS number. Always check it with the standard checksum algorithm before calling PDS; a simple validation step avoids unnecessary round trips when digits are transposed in transcription.
When the NHS number is unknown, you’ll rely on demographic search. Normalisation is king: strip titles and suffixes from names, de-accent characters, handle common hyphenation, uppercase and space-normalise postcodes, and be lenient to punctuation in addresses. Names can be the trickiest attribute—think nicknames, transliterations, and marital changes—so give your users good affordances to refine a search without starting over, such as adding a previous name or past postcode. In designs where space allows, make the candidate list dense with disambiguation cues (age, partial address, registered GP practice) but personable; clinicians recognise people, not record keys.
False positives are more dangerous than false negatives. If a demographic search returns multiple plausible matches, steer users to pick deliberately rather than auto-binding to the “top” candidate. Build in the concept of “tentative link”: a local association to a PDS candidate that requires confirmation—by a second check, a barcode on a wristband, or a signed action—before downstream actions can rely on it. In telephone or online settings, pair search with knowledge-based verification (for example, asking for parts of the address or GP practice) to increase confidence while being inclusive.
Once you have a confirmed identity, protect and propagate it. Inside your estate, standardise on a single patient identifier as the primary key—usually the NHS number—and avoid ever creating another source of truth. For legacy systems that still depend on local identifiers, maintain a mapping service and design it as a first-class component: it should handle merges (when two local records prove to be the same person), splits (when a mistaken merge is reversed), and deprecations cleanly. Producing safe, human-comprehensible audit logs for these events will save you in incident reviews.
Demographics change, and drift is inevitable. Rather than pulling the full record on every screen load, consider subscribing to demographic change events. PDS Notifications (published via NEMS and delivered to you through MESH) let you receive changes such as address updates so you can refresh your cache and trigger downstream processes (like updating letters or re-assessing eligibility). This event-driven model reduces polling load and keeps your local view fresh without taxing clinicians.
Edge cases deserve design time. Newborns can have delayed issuance of NHS numbers; recent migrants may have no number yet; name order and character sets vary by culture; safeguarding flags and proxy contacts require delicacy; and “sensitive” records may mask or limit certain demographics. Expose these conditions explicitly in the UI with plain-English explanations and safe defaults. For example, if a record is flagged as sensitive, default to minimising on-screen exposure and logging access decisions carefully.
The last pillar of quality is performance. Clinicians notice 500-millisecond delays, and their patience is rightly short. Use connection pooling, HTTP/2 where supported, and compressed responses. Make the most of partial displays: render the last-seen demographics instantly from cache with a “refresh from PDS” affordance that updates the panel asynchronously. If you implement optimistic UI patterns, always show the provenance and timestamp to avoid the appearance of “fact” when you’re displaying cached data.
Integrating with national services is not the same as wiring up a commodity SaaS API. You will move through sandboxes, integration test environments, assurance, and controlled go-lives. Design your engineering process with that journey in mind, and you’ll save months.
At a minimum, prepare for three environments: local (mocked), pre-production (NHS integration environment), and live. For local development, generate representative FHIR Patient payloads and deterministic match scenarios. Build contract tests around your PDS adapter so that query construction and response parsing remain stable as you iterate. In your integration environment, expand to end-to-end scenarios with security (CIS2 tokens or application credentials as appropriate), realistic error conditions (timeouts, throttling, partial outages), and representative data volumes. Clinical safety testing should run in parallel, with hazard analysis that explicitly lists wrong-patient selection risks and mitigations (for instance, human confirmation requirements or barcode scanning).
What to test before go-live
Your accreditation pathway will vary by provider type and product scope, but expect evidence of both technical conformance and clinical safety. Where you intend to use application-restricted access—for instance, a backend service that validates NHS numbers—study the PDS guidance on what is and isn’t permitted in that mode, and document the controls that prevent escalation of purpose. User-restricted access will require your CIS2 integration to be demonstrably robust, with role mapping and audit aligned to your organisation’s security policy. The good news: these patterns are well trodden, and the developer guidance is explicit about how to integrate.
Monitoring closes the loop. Treat each PDS call as a patient-safety event with operational telemetry. Emit metrics for query counts, unique vs multi-match rates, errors by type, latency percentiles, and cache hit ratios. Build SLOs around what matters clinically—time to verified identity on the first search, rate of wrong-patient near-misses avoided, percentage of demographics refreshed within a business day. Feed those metrics into a central dashboard, and attach alert policies that wake a human only when action is possible (for example, a spike in “no match” outcomes after an upstream change). Pair the metrics with structured logs that include correlation IDs, user IDs (pseudonymised for operations), and request fingerprints (search parameters hashed) to make on-call investigations humane.
Operational playbooks are the other half of reliability. Write runbooks for common incidents: “PDS latency > 2 seconds,” “Authentication failures due to CIS2 outage,” “MESH message backlog for notifications.” Include steps to rollback client changes, switch to read-only, or toggle a “degraded mode” banner in clinician-facing apps. Practice your incident drills, including communications to front-line teams (“identity is slower than usual; use barcode scanning and NHS numbers where possible”) so that everyone knows how to stay safe during degradation.
A good PDS integration project follows an intentional path. Use the outline below as a blueprint; adapt details to your environment and governance.
Begin with your user stories: who is querying identity, in what context, and for what decisions? If the actor is always a healthcare worker at a device (for example, EPR lookups, clinic receptions, pharmacy A&E liaisons), plan for user-restricted access via CIS2. If you have headless jobs (such as background validation of imported NHS numbers), consider application-restricted access—but validate that your use case is allowed in that mode and accept its narrower capabilities (for instance, no multi-result search or writes). Err on the side of user-restricted for interactive clinical tasks; it is safer, more flexible, and aligns with “purpose of use”.
Stand up your identity integration first. Choose a robust OAuth/OIDC library in your stack; set up token storage policies; implement log-out, token refresh, and a small admin console that shows the current authentication status and scopes to help testers and clinicians troubleshoot. For smartcard-heavy sites in transition to CIS2, run pilots with alternative factors (e.g., platform authenticators or security keys) and measure sign-in friction. Small gains here compound into minutes saved in clinic and fewer help-desk tickets.
Write a dedicated client that hides HTTP plumbing and FHIR specifics. Provide high-level methods for NHS-number reads, demographic traces, and updates where authorised. Implement rigorous input validation: NHS number checksum, postcode formats, date normalisation. On the output side, map PDS fields into a stable internal structure so that the rest of your system is decoupled from PDS schema changes. Wrap calls with resilient patterns—timeouts, retries with jitter, and circuit breakers that trigger a cached-read-only mode when PDS is experiencing issues.
Bring designers and clinical safety officers into the search and selection patterns. Show match confidence transparently. Offer quick pivots from demographic search to barcode or NHS number input. Capture the clinical reason for identity updates and require a second check for sensitive writes. Reflect “PDS last verified” timestamps and sources at the point of decision-making. If your system supports remote or telephone triage, design consent and knowledge-based verification into the script so that identity isn’t guessed under pressure.
If your processes depend on up-to-date addresses, contact preferences, or GP registrations, subscribe to PDS Notifications via NEMS and consume them through MESH. Make your consumer idempotent and tolerant of re-ordering; store an “applied up to” marker so you can replay messages if necessary. Downstream, update caches and emit domain events to re-render UIs and re-evaluate eligibility rules. This pattern beats polling on every screen by orders of magnitude and reduces upstream load.
Document how your flows map to the user-restricted or application-restricted patterns in the guidance; capture screen recordings of search and selection edge cases; include logs showing scopes and audit metadata; and attach screenshots of your fallback modes. If your organisation runs a Clinical Safety Case (and it should), include hazards like “Selection of wrong person from candidate list” with mitigations and test evidence. The effort pays off during go-live approvals and in the first clinical week.
When incidents happen, clinicians need quick, plain-English answers. Build a status banner in the application that you can toggle remotely (“National demographics lookup is slower than usual; results may take ~3 seconds. Continue to use NHS numbers where possible.”). Provide a “Verify later” workflow that queues a PDS refresh and highlights records that need reconciliation once services normalise. On the engineering side, adopt blameless reviews where every outage teaches the system something new—be it a shorter timeout, a clearer message, or a more generous cache TTL.
Over-relying on cached demographics without trust signals. Caching is essential, but showing stale data as if it were ground truth erodes safety. Always attach provenance (“PDS verified at 10:41 today”) and give a one-click refresh. If you surface demographic data across multiple apps, centralise the cache so consistency improves rather than diverges.
Assuming demographic search will always produce a unique match. In busy urban populations, names and ages collide. Design your UI to make multi-candidate selection fast and safe; never auto-select the “top” result because it looks close enough.
Treating identity updates as free-text changes. An address change is a serious event; it affects correspondence, eligibility, and safeguarding. Tie updates to explicit reasons, permissions, and audit. Apply business rules to prevent destructive edits (for example, overwriting a verified NHS number with a guessed one).
Confusing access modes. Teams sometimes prototype with application-restricted access then forget to realign the design for user-restricted, where richer features exist and audits expect user identity propagation. Start with the right mode to avoid rework and rejected assurance.
Ignoring the wider Spine choreography. PDS may be step one, but endpoint discovery and downstream interactions depend on it. Wire up the full dance in your test harness so that functional gaps show up before clinicians do.
Standards and platforms evolve. The shift towards CIS2 and modern authentication will continue, gradually retiring legacy smartcard-only approaches. Designing around open standards (OAuth 2.0/OIDC), token-agnostic security modules, and a clean separation between identity and business logic will keep your codebase nimble. If you build for user experience as much as for protocol conformance—fast, forgiving search; explicit confidence signals; crisp error messages—your integration will wear well even as APIs add capabilities or tighten constraints.
Consider investing in observability early. As your organisation connects more national services, being able to see identity as a first-class flow—search volumes, time to verification, candidate rates by clinic, event lag for notifications—will help you plan staffing, uncover training needs, and quantify quality improvements. The same telemetry makes your clinical safety case live and actionable rather than a static document.
Finally, keep a close relationship with the national developer community. Release notes and forum threads often flag subtle changes—address element mappings, search edge cases, sandbox data corrections—before formal documentation catches up. Periodic reviews of your audit logs and error traces, cross-checked against platform updates, will keep surprises to a minimum.
Implementing the NHS PDS FHIR API is far more than a technical box-tick. It is the gateway to reliable patient identity, and therefore to safe care, seamless interoperability and operational efficiency. The recipe is straightforward but non-negotiable: design a clean architecture that centralises identity logic; implement CIS2-backed security with least privilege and excellent auditability; treat matching as a safety-critical discipline; subscribe to events instead of polling; and invest in testing, clinical safety, and operations from day one. Do this well and your clinicians will barely notice the identity machinery—everything will simply work, quickly and safely, for the person in front of them.
Is your team looking for help with NHS PDS integration? Click the button below.
Get in touch