PDS FHIR API technical conformance: healthcare worker access mode

Show your technical conformance for access to the PDS FHIR API and its healthcare worker access mode.

Overview

As part of the onboarding process for the PDS FHIR API, you need to show that your software meets our requirements.

This API has two access modes, each with different authentication methods and functionality. The access mode your software product uses affects which criteria you need to meet.

You'll need to meet these requirements, where they are relevant to your software, during onboarding.

The access modes are:

restricted access mode
healthcare worker access mode

This page explains the technical conformance requirements for healthcare worker access mode.

To onboard for the PDS FHIR API in healthcare worker access mode there are 73 main technical conformance questions in 4 areas:

General requirements
Requirements for search
Requirements for 'retrieve by NHS number'
Requirements for making PDS updates

General requirements

Use cases

You need to provide us with details of how your software product uses this API, including:

what care settings it's used in
which key use cases involve this API
which API endpoints you're using

Role-based access controls (RBAC)

If you support searches that return multiple patients, or updates, you must use the National RBAC model to ensure that only users with appropriate roles are able to access the API.

This does not apply if you only support retrievals and/or searches with a unique match.

User Profile ID (URPID) for calling the PDS FHIR API

This must be the URPID for the role that the user selected for their current session (either at the point of sign in or subsequently).

Requirements for search

Matching level

It's important that users select a matching patient based on the patient data, not on the perception of how good the match is.

Therefore, you must not display the Matching Level with the search results.

Display search results in the order returned from PDS

Local systems must display search results in the order returned from PDS.

Sensitive patient flag

If a sensitive flagged record is returned in a trace, the flag must not be displayed to the user on a search results screen.

Warn the end user that a patient is sensitive

If a sensitive record is selected from a ‘pick-list screen’ or detected during the course of syncing, the local system must warn users accessing the patient’s record that the record is sensitive, regardless of role-based access controls (RBAC) rights.

Warn the user when including information about a sensitive patient

The warning message displayed by the local system must advise the user:

that, if role-based access controls (RBAC) is used to restrict access, unless they have the appropriate RBAC rights they will not be able to view or amend location data for the patient
that updates to the record will not be sent to the PDS
that no new NHS number allocation should be made for this patient

Requirements for 'retrieve by NHS number'

Sync your Local Patient Index

If you retrieve patient data from PDS, you must ensure it is kept up to date. This is important for data quality, but especially important to protect sensitive patients. If a patient has been classified as sensitive it's important not to share location details you may have retrieved from PDS before they were sensitive.

Sync a patient record with PDS

Sync any locally held copy of a patient record with PDS at the following events:

the commencement of an episode
prior to using patient communication information
prior to inpatient admission and discharge
prior to any retrieval of clinical or medication information stored on external Spine services

Provide care if syncing fails

Where syncing fails at one of the ‘Significant Events’, local systems must continue to be able to provide care for a patient.

Warn the end user of key field changes

Where there is an interactive user, in addition to the use of the version ID and/or manual comparison of fields, if the local system detects that changes have occurred to the key-fields on the PDS (e.g. the death notification status has been set or the gender altered), that user must be informed.

Allow the end-user to review key field changes

Interactive users must be given the opportunity to review and if necessary reject a change in the key-fields when syncing with PDS.

Accept key field changes if no end-user is present

Where there is no interactive user, or where the logged-on user has read-only access to the system and the records have previously been synchronised, the system must accept updates to key-fields from the PDS.

Read the 'consent to share' status

Local systems must be capable of reading 'consent to share' status on the PDS.

Allow express dissent status to be overridden

Local systems must allow a consent status of ‘2’ (Express Dissent) to be overridden.

Restrict access to override dissent

Local systems must restrict the ability to override dissent to only those eventualities and roles outlined in NPFIT-FNT-TO-IG-DES-0135: NHS CRS Consent / Dissent: Information Sharing Rules.

Warn the end-user of a superseded patient record

In user-interactive processing, on receipt of a superseded patient resource from the PDS, the local system must warn users accessing the patient’s record that the local record is wrongly identified.

Required information when warning of a superseded patient record

The warning message displayed by the local system must advise the user:

that the NHS number being used has been replaced
that the patient should be informed of the replacement number (where possible)

Replace the NHS number for a superseded patient record

On receipt of a Superseded Record code, if the new NHS number returned in the response is not present on another record in the local database, the superseded number must be replaced with the superseding number.

Refer superseded record confusion cases to Local Back Office

On receipt of a Superseded Record code, if the new NHS number returned in the response is present on another record in the local database, then the superseded record must continue to be used for the purposes of this episode of care and the Local Back Office must be notified.

Warn the end-user of an invalidated patient record

In a user-interactive process, on receipt of an Invalid NHS number code from the PDS the local system must warn users accessing the patient’s record that the local record is wrongly identified.

Invalidated patient record warning messages

The warning message displayed by the local system must advise the user:

that the NHS number being used is no longer valid
that the record is being referred to the Local Back Office for processing
that all demographic and clinical information for this patient should be regarded with caution until the processing is complete.

Local systems may mark the record in such a way that every time it is accessed all users are made aware:

that there are data anomalies on the record which could constitute a clinical risk
that the anomalies may pertain as much to the clinical as the demographic record

De-couple an invalidated patient record from PDS

On receipt of an Invalid NHS number code, the wrongly identified local record must be de-coupled from the PDS.

De-coupling will exempt the local record from further syncing until it has been re-coupled and the Version ID reset to 0. It should also trigger a Local Back Office task to resolve.

Role-based access controls (RBAC) rights for sensitive records

If a Sensitive record code is returned from PDS, the local system should not display the following data held on the matching local system record, unless the logged-on user has the appropriate role-based access controls (RBAC) rights to view this information:

patient addresses
telecoms information
related persons
GP practice/pharmacy data

Access to the location details on the record must be restricted using role-based access controls (RBAC).

Users with appropriate access rights must continue to be able to access and update location information held locally only.

Where local, restricted, ‘location’ information is present, this data must not be overwritten with blank data from PDS on record syncing.

Making PDS updates

Updating patient details is an extra feature. If you use it, you must meet the additional technical conformance criteria outlined in this section.

Requirements for making PDS updates

Does your product need to update patient details?

Updating patient details is an extra feature. If you use it, you must meet the additional technical conformance criteria outlined in this section.

Does your product reject an entire PDS response message due to invalid data items?

An entire PDS response message must not be rejected where individual items of data are invalid.

Does your product persist and use objects from the PDS with unpopulated optional elements?

Local systems must be able to persist and use objects from the PDS which contain unpopulated optional elements.

Does your product update a matched local record with PDS data?

The local system must be capable of updating any matched local record with PDS data.

Does your product store the Version ID locally?

Local systems must store the Version ID locally in order determine synchronisation behaviour.

Does your product appropriately handle rejections by implementing the required outcomes?

If the interactive user rejects an update to the key-fields, the local record must be:

de-coupled from PDS
referred to the Local Back Office for further investigation

Does your product enable the end user to confirm the match?

Where a matching record returned by the LPI or PDS in response to a trace is selected, a user must be prompted to confirm that the displayed record belongs to the patient.

Does your product allow de-coupled records to update PDS?

De-coupled records must not be used to update the PDS.

Does your product allow de-coupled records to be updated locally?

De-coupled records must be capable of being updated locally.

Does your product enable management of de-coupled records?

Local systems must provide tools to manage de-coupled records.

Does your product support selecting of data at the object level?

Selection of data from each source must be at the object level e.g. the whole 'home' address, not individual address lines.

Does your product support the display of all prefixes?

Local systems must be able to display any name prefix value returned by the PDS.

Does your product reset locally-held Version ID information for a superseded record?

The system must reset any locally-held Version ID information for the superseded record.

Does your product notify the Local Back Office if an invalid record is encountered?

Local systems must notify the Local Back Office that an invalid record has been encountered.

Does your product include the NHS number when notifying the Local Back Office of an invalid record?

The notification must contain the affected record NHS number.

Does your product support sensitive flag synchronisation?

Local Systems should continue to attempt record synchronisation with the PDS at subsequent significant events, so that it can be detected whether a sensitive flag has been removed from the record.

Does your product synchronise a locally stored patient before a PDS update?

Systems must synchronise a locally stored patient record prior to performing a PDS General Update.

Does your product support the rules for local systems with LPI?

If the local system has an LPI it must update the PDS whenever local patient demographics are amended, except if:

the PDS is unavailable, at which point, the local system must indicate that the records are now not synchronised
the only data amended is not held on the PDS e.g. ethnicity
the only data amended is explicitly exempt from update on the PDS e.g. primary care information from secondary care
the record is sensitive or invalid e.g. S flagged records or records identified by an invalid NHS number
the local record is de-coupled from the PDS or in an unsynchronised state e.g. there is an erroneous death status set on the PDS

Does your product support the management of the Version ID?

The Version ID must be reset to 0 upon sending the PDS Update.

Does your product alter the use of name, address or telecom details when managing PDS objects?

When altering name, address or telecom objects, local systems must not change the 'system' or 'use' e.g. a 'mobile' must not be changed to 'home'. The prior object must be removed, and a new one added instead.

Does your product attempt to add PDS objects that already exist?

Local systems must not attempt to ‘add’ objects which already exist.

Does your product attempt to replace or remove PDS objects that do not exist?

Local systems must not attempt to ‘replace’ or ‘remove’ objects which do not exist.

Does your product support the rules for replacement?

Local systems must not attempt to remove any of the following objects without providing a replacement value:

usual name
gender
date of birth
date of death

Does your product support the minimum data set for update?

Local systems which retrieve from and update PDS must support the following minimum dataset:

one and only one current usual name
person gender
date of birth
one and only one current home address

Does your product have the required data set support?

Local systems which retrieve from and update PDS should support the following data items:

one and only one current usual name and nickname
date of death
one and only one current temp, home and billing address
one and only one current home telephone number
one and only one current mobile telephone number
language and interpreter required indicator

Does your product validate data before updating PDS?

Local systems must validate data prior to updating PDS.

Does your product validate dates before updating PDS?

When dates are added or updated on the PDS, they must be sent as valid, full dates in the required format.

Does your product validate against relevant vocabularies before updating PDS?

Any vocabulary data contained in an update must be validated against the appropriate vocabulary in the specifications.

Does your product support 'business effective from' dates where appropriate?

A ‘business effective from’ date must be provided where an object supports business effective dates.

Does your product remove objects from PDS where they are to be rendered no longer valid?

With the exception of the type 'home' address (Usual address), where an object is to be rendered no longer valid from the current moment (e.g. it is end-dated on the local system with an end date that is not in the future), and no replacement value is being provided, then it must be removed from PDS.

Does your product avoid adding 'business effective from' dates that are in the future?

When updating PDS, ‘business effective from’ dates must not be set in the future.

Does your product derive addresses from a PAF tool when updating PDS?

Local systems must be capable of deriving addresses from a PAF tool when performing updates.

Does your product support postcodes that conform to the PAF format?

The postcode must conform to the PAF format e.g. a single space character must separate the ‘outcode’ and ‘incode’.

Does your product support the manual population of addresses?

Where an address cannot be found in the PAF tool or a PAF tool is not supported, systems must enable the user to manually populate the address according to the prescribed format.

Does your product support the default postcode for 'no fixed abode' addresses?

For ‘no fixed abode’ addresses, the postcode field must contain the default postcode ‘ZZ99 3VZ’.

Does your product enable the updating of primary care information on the PDS?

Systems other than NHAIS, GP Practice and DSA must not update primary care information on the PDS.

Does your product enable the removal of primary care information on the PDS?

Systems other than NHAIS or DSA must not ‘remove’ primary care information from the PDS.

Does your product enable the updating of registered GP practice information on the PDS?

Primary care systems must not update registered GP practice information as part of GP registration functionality. This information must not be changed on the PDS for any other purpose.

Does your product enable free-text entry when updating primary care information on the PDS?

Where primary care data is added to the update request, the user interface must not allow free-text entry of coded data, but provide lookup functionality.

Does your product record informal death status for death notifications when updating PDS?

Where there is a legitimate business need to submit death notifications, local systems must be capable of recording (e.g. setting) informal death status on the PDS.

Does your product enable removal of a previously set death status when updating PDS?

Local systems must not attempt to un-decease the patient on the PDS, by ‘removing’ a death status once set.

Does your product enable changing death status when updating PDS?

Local systems must not update the death status recorded on PDS from a ‘2’ (formal) to a ‘1’ (informal).

Does your product support language definition where the interpreter required indicator is used?

If the interpreter required indicator is to be updated on PDS then a language defined in the language vocabulary must also be included in the update.

Does your product only support pharmacy codes that are Spine-compliant?

Local systems must only update the PDS with codes that are for Spine-compliant pharmacies.

Does your product reset the Version ID when required?

If an update fails as a result of a Version ID failure, the Version ID must be reset to force a manual synchronisation at the next significant event.

Does your product support the management of related persons?

If supporting related persons, local systems must support the update of related persons not identified by NHS number.

Does your product remove invalid NHS numbers for related persons when updating PDS?

When an invalid NHS number is detected for a related person record, local systems must remove that related person record and prompt the user to add a new related person record using demographic data.

Contact details data quality

Find out about contact details data quality.

Next steps

You'll need to agree to these technical conformance terms of service in order to use the PDS FHIR API, as part of our online digital onboarding process.

To get started, send us an email at [email protected].

Last edited: 3 February 2026 1:27 pm