Skip to main content

Migrating from the PDS SMSP API to the PDS FHIR API

The PDS SMSP API is deprecated. Learn what's involved in migrating your application to use the PDS FHIR API.


On 14 October 2021 we deprecated our Personal Demographics Service - SMSP API. It is still available for use, and is still fully supported, but we will not be adding new features. The API will be retired on 31st January 2024, meaning it will not be available for use after that date.

Note: This only affects you if you use our PDS SMSP API, not if you use a third party PDS SMSP provider.

If you need continued access to PDS, we recommend that you migrate your application to use the Personal Demographics Service - FHIR API.

This page explains what's involved.

Why we have deprecated the PDS SMSP API

We’ve built a new API that provides equivalent functionality - the PDS FHIR API.

As per our deprecation and retirement policy, we must ensure that public funds are used efficiently and cannot afford to maintain replaced APIs indefinitely.

Why we have not deprecated third party PDS SMSP providers

This deprecation announcement only affects the PDS SMSP API that we developed, and does not apply to you if you use a third party PDS SMSP provider. 

These are commercially available products which give easier access to PDS than our PDS HL7 V3 API. You can see a list of conforming products in our Conformance Catalogue.

These third party SMSP providers use our PDS HL7 V3 API under the covers, but with a simplified read-only model. We are not deprecating our PDS HL7 V3 API and also not these third party PDS SMSP providers.

What deprecated means

Deprecated means:

  • the API is still available for use
  • full service levels still apply
  • we are unlikely to make any updates to it
  • new integrations are not allowed - although in-flight integrations can continue
  • we intend to retire it at some point

We have not yet decided on a retirement date - we will consult with existing users before making a decision.

About the PDS FHIR API

The PDS FHIR API is our strategic API for accessing PDS. It replaces the PDS SMSP API and will eventually also replace the PDS HL7 V3 API.

It has a number of benefits over the PDS SMSP API:

  • it includes additional data items - pharmacy details, death notification status and alternative names and contact details
  • it supports gender-free search
  • it supports retrieval by NHS number alone - no need for date of birth
  • it is internet-facing
  • it conforms to FHIR - the most modern healthcare interoperability standard
  • it uses OAuth 2.0 with signed JWTs for security, which makes rotating your security credentials easier
  • it has an easier onboarding process

Summary of differences

Area Differences
Additional data items The PDS FHIR API includes a number of data items that are not available via the PDS SMSP API, namely:
  • alternative names - such as temporary, maiden or nicknames
  • alternative contact details - such as work phone or textphone
  • death notification status - formal or informal
  • pharmacy details
Business effective dates

Some data items in PDS have "business effective dates" which specify the time period to which they apply - which might be past, present or even future. This concept applies to names, addresses, contact details, emergency contact people, related people and registered GP practice.

The PDS SMSP API includes logic to include only the most appropriate data values, based on the current date.

The PDS FHIR API includes all data values, which provides more flexibility but also requires the calling system to decide which value to use.

We are considering adding a feature to the PDS FHIR API that would allow you to receive just the current data. If you think this would be useful, you can upvote the feature on our interactive product backlog.

Gender-free search

With the PDS SMSP API, you must specify the patient's gender in a search. This can cause problems because for some people, the gender held in PDS might not match the gender they identify with. These are edge cases but are important because gender can be a sensitive issue for the people in question.

With the PDS FHIR API, you do not have to specify gender in a search.

Retrieve by NHS number

With the PDS SMSP API, you must include both the NHS number and the date of birth to retrieve a patient's record.

With the PDS FHIR API, you only need to include the NHS number to retrieve a patient's record, not the date of birth. However, we do recommend you verify that you have the correct patient record, for example by checking the date of birth and other basic demographics, or by using the search function and then checking the NHS number.

GP details

The PDS SMSP API includes full details of the registered GP practice - name, address etc.

The PDS FHIR API provides the ODS code for the registered GP practice. If you need the full details, you must get them from the Organisation Data Service (ODS), for example using the ODS FHIR API.

This is a deliberate design decision - our newer APIs are, in some cases, more granular.

Network access The PDS FHIR API is available on the internet and HSCN. The PDS SMSP is only available on HSCN.

The PDS SMSP API uses TLS MA to authenticate the calling application. You must renew your TLS MA certificate on an ongoing basis which involves a handshake with us.

The PDS FHIR API uses OAuth 2.0 with signed JWTs to authenticate the calling application. You should rotate your JWTs on an ongoing basis but you can do this without our involvement.

API format

The PDS SMSP API uses SOAP and XML, and the payload conforms to HL7 V3, with an ITK wrapper.

The PDS FHIR API is RESTful and conforms to FHIR R4. To call it you make a simple HTTP request to a named endpoint, and the requests and responses are in JSON format. FHIR libraries are available to make it easier to generate requests and parse responses.

Verify NHS number / cross-check trace

The PDS SMSP API provides a specific function to verify an NHS number, sometimes referred to as a "cross-check trace".

The PDS FHIR API supports this indirectly via search - you search for a patient and then check the NHS number found against your records.


The PDS FHIR API has two test environments:

  • a sandbox for early developer testing, which provides canned responses to a limited number of scenarios
  • an integration testing environment for formal integration testing, which is pre-loaded with 100+ test patients to cover a wide variety of scenarios

Both environments are self-service - although in the short term, setting up your signed JWT key for integration testing needs our input.


We have tried to make onboarding to the PDS FHIR API as quick and easy as possible. In particular:

  • the PDS FHIR API uses our new Digital Onboarding Service, which makes onboarding quicker and more transparent
  • the governance and assurance requirements are virtually identical to the PDS SMSP API, and are all self-certified
  • if you're migrating from the PDS SMSP API, you won't have to re-submit a PDS Access Request
  • we have a dedicated onboarding lead to assist developers who are migrating from the PDS SMSP API

How to migrate to the PDS FHIR API

As per our getting started guidance, here’s what you’ll need to do:

1. Create a developer account

If you create a developer account on our API platform, we can let you know of any important updates.

2. Design and build your changes

Change your software to call the PDS FHIR API instead of the PDS SMSP API. In particular:

  • change the format of your requests
  • change your software to use signed JWT authentication instead of TLS MA authentication
  • change your code to deal with the response, which is in FHIR/JSON format instead of SOAP/XML. There are FHIR libraries to help with this

3. Test your changes

Use our self-service sandbox and integration test environments to test your integration.

4. Get your software onboarded

Use digital onboarding to get approval to go live. The governance and assurance requirements are identical to those for the PDS SMSP API, and are all self-certified, so onboarding should be quick and easy.

To book a time slot for your technical conformance testing, contact us at [email protected]. We have a dedicated onboarding lead to assist developers who are migrating from the PDS SMSP API to the PDS FHIR API. 

Help and support

For specific help on the PDS SMSP API, including migrating to the PDS FHIR API, contact us.

Last edited: 16 November 2023 2:26 pm