Skip to main content

Personal Demographics Service - HL7 V3 API

Access patients' personal information, such as name, address, date of birth, related people, registered GP and NHS number using our HL7 V3 API.

This API is in production, but under review for deprecation. We will contact you before agreeing to a retirement date.

If you are developing a new integration, consider using the Personal Demographics Service FHIR API instead.

If you have any concerns, contact us.


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, registered GP 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 - although another option is PDS Notifications FHIR API
  • 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

A healthcare worker must be present and authenticated with an NHS smartcard or a modern alternative to use this API.

Spine Mini Service Provider (SMSP) options

There are also commercially available products which give easier access to PDS, known as Spine Mini Service Providers (SMSPs).

These and other conforming software products are listed in our Conformance Catalogue.

If you are interested in becoming a provider of one of these products, see Personal Demographics Service - SMSP API standards.

Who can use this API

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). 

API status

This API is in production, but under review for deprecation. We will contact you before agreeing to a retirement date.

Service level

This API is a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year.

For more details, see service levels.


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 do not require an immediate response or might take longer, for example:

  • PDS advanced trace query (search)
  • PDS general update
  • PDS birth notification (outbound from PDS)

Asynchronous messages are of two types:

  • unreliable - where it is OK to lose a message, such as in advanced trace (search)
  • reliable - where it's not OK to lose a message, such as in updates, NHS number allocations and birth registrations

For more details, see HL7 V3.

Message Handling System (MHS) adaptor

To remove the complexity of building your own Message Handling System, we offer a pre-assured, client side MHS adaptor that you can integrate into your own infrastructure.

It makes it easier to connect to the NHS Spine and perform business operations by exposing a RESTful API that conforms to the HL7 V3 standard

Network access

You need a Health and Social Care Network (HSCN) connection to use this API.

For more details, see Network access for APIs.

Security and authorisation


This API is user-restricted, meaning an end user must be present and authenticated to use it.

The end user must be:

  • a healthcare worker
  • strongly authenticated, using either an NHS smartcard or a modern alternative

We support the following security patterns:

  • user-restricted HL7 V3 API, using NHS Care Identity Service 2 (NHS CIS2)
  • user-restricted HL7 V3 API, using CIS

For more details see user-restricted APIs.


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 page

Environments and testing

You can test this API using our Path to Live environments.

The live environments are as follows:

Purpose Base URL
PDS synchronous - all PDS retrieval interactions

PDS asynchronous unreliable - PDS advanced trace (search)
PDS asynchronous reliable - PDS update, allocate NHS number, birth registration request


You must get your software onboarded before it can go live.

This API uses the Common Assurance Process (CAP) which is tailored for each NHS service.

For more details, see the PDS Common Assurance Process which explains how to get started with onboarding.


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

This is a Microsoft Word file. To request a different format, contact us

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.

This is a Microsoft Word file. To request a different format, contact us.

RBAC Guidance document

Guidance on implementing role-based access controls (RBAC) for the Personal Spine Information Service (PSIS) and the Personal Demographics Service (PDS).

This is a Microsoft Word file. To request a different format, contact us.

Last edited: 7 November 2023 11:12 am