We have detected that you are using Internet Explorer to visit this website. Internet Explorer is now being phased out by Microsoft. As a result, NHS Digital no longer supports any version of Internet Explorer for our web-based products, as it involves considerable extra effort and expense, which cannot be justified from public funds. Some features on this site will not work. You should use a modern browser such as Edge, Chrome, Firefox, or Safari. If you have difficulty installing or accessing a different browser, contact your IT support team.
Personal Demographics Service - HL7 V3 API
Access patients' personal information, such as name, address, date of birth and related people using our HL7 V3 API.
Overview
If you are developing a new integration, consider using the Personal Demographics Service FHIR API instead.
Use this API to access the Personal Demographics Service (PDS), the national electronic database of NHS patient details such as name, address, date of birth, related people and NHS Number.
You can:
- search for patients
- check that you have the correct NHS Number for a patient
- get patient details
- create a new record for a birth
- receive birth notifications
- create a record for a new patient (except for GPs - see below)
You should not use this API to create a new record when registering a new patient at a GP Practice. Instead, use National Health Application and Infrastructure Services (NHAIS).
You can retrieve current and historical demographic information for a patient including:
- NHS Number
- name
- gender
- birth information
- address
- contact details
- registered GP
- preferred pharmacy
- consent information
- related people, such as next of kin
- death information
Legal use
This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. To do this, make a PDS access request.
You must do this before you can go live (see ‘Onboarding’ below).
Related APIs
The following APIs also give access to the Personal Demographics Service:
-
Personal Demographics Service - FHIR API - use this new API to search for patients, retrieve patients by NHS Number and update patients.
-
Personal Demographics Service - SMSP API - use this if you want to get PDS data without an authenticated end user (no smartcard required). It is, however, read-only and searches are limited to a single result.
The following APIs are also related to this API:
-
Organisation Data Service - FHIR API - use this to get full details for the organisations related to the patient, such as their registered GP or nominated pharmacy.
API status
This API is stable.
Technology
This API is an HL7 V3 API. It is a mixture of:
- synchronous interactions, using HL7 V3 SOAP web services
- asynchronous interactions, using HL7 V3 ebXML messaging
The synchronous pattern is used for interactions which need an immediate response and run quickly, for example:
- PDS Simple Trace Query
- PDS Retrieval Query
The asynchronous pattern is used for interactions which either don’t require an immediate response or might take longer, for example:
- PDS Advanced Trace Query
- PDS General Update
- PDS Birth Notification (outbound from PDS)
For more details, see HL7 V3.
Network access
You can access this API via:
- the Health and Social Care Network (HSCN)
- the internet - but note that devices using NHS smartcards do require HSCN access
For more details, see Network access for APIs.
Security and authorisation
Authentication
This API is user-restricted, meaning an end user must be present and authenticated to use it.
The end user must be:
- a healthcare professional
- strongly authenticated, using either an NHS smartcard or a modern alternative
We support the following security patterns:
- user-restricted HL7 V3 API, using NHS Identity
- user-restricted HL7 V3 API, using CIS
For more details see user-restricted APIs.
Authorisation
For some activities, the end user must be authorised to perform that activity.
The API itself does not perform any authorisation checks. Rather, the calling system is expected to perform them. The authorisation rules are specified in our national Role Based Access Control (RBAC) database.
For more details see:
- the PDS Integration Requirements document in the 'additional guidance' section below
- the RBAC guidance document in the 'additional guidance' section below
- our national Role Based Access Control (RBAC) database on the registration authorities and smartcards page
Testing
You can test this API using our Path to Live environments.
Onboarding
You must get your software onboarded before it can go live.
As part of onboarding, this API uses the Common Assurance Process (CAP), which is tailored for each NHS service. For more details see the PDS Common Assurance Process.
Interactions
For a full list of interactions for this API, see the PDS section in the Spine Message Implementation Manual (MIM).
For details on the general structure of the interactions, see HL7 V3.
Additional guidance
PDS Integration Requirements document
Provides guidance and specifies requirements for systems integrating with PDS using the HL7V3 API, including:
-
tracing: searching for, recognising and confirming patient identity for a record held either locally or on the PDS
-
synchronisation of locally held records with PDS counterparts
-
flagged records: the process of detecting a record flagged as ‘invalid’ or ‘sensitive’ on Spine and how these records should be managed
-
updates: the process of updating a patient’s demographic record on the PDS
-
Local Back Office: the actions that are required to manage such scenarios as duplicate and confused local records
-
allocating new PDS records for patients
-
birth notifications: the maternity unit process for creating a new record on PDS for a birth and the Child Health Organisation actions required for receiving new births from the Spine
PDS Integration Guidance document
Detailed guidance on integration with each of the interactions in the PDS HL7V3 API, including data field-level business and validation rules.
RBAC Guidance document
Guidance on implementing role-based access controls (RBAC) for the Personal Spine Information Service (PSIS) and the Personal Demographics Service (PDS).