Get and update contact details in PDS

This standard builds on the GOV.UK design system, which details how to ask users for email addresses and phone numbers. This standard applies these rules for the Personal Demographics Service (PDS).

Within PDS, a number of methods exist to contact a patient. This standard explains how to use these contact details directly within a service. For sending communications, see NHS Notify.

Depending on the API you use, the data presentation specification to get data from the PDS database will be different.  

The APIs that interact with PDS data are:

1. Personal Demographics Service (FHIR) API - Access patients' personal information, such as name, address, date of birth, related people, registered GP, nominated pharmacy and NHS number using the FHIR version of the Personal Demographics Service (PDS) API.
2. Personal Demographics Service (HL7 V3) API - use this if you want to use functions that are not yet available on the FHIR API, such as creating a new record for a birth, receiving birth notifications, or creating a record for a new patient (except when registering a new patient at a GP Practice, use Primary Care Registration Management).

There is no requirement to verify ownership of contact details before sending the contact detail to PDS. You can authenticate the contact detail via a one-time passcode to check the patient has entered the correct contact detail, though this may cause your organisation additional cost for SMS messages and letters. 

Proof of address is not required to update an address on a PDS record. It should not be used to determine residency status or to confirm if the individual is entitled to free hospital treatment.

Within PDS, you can get different telecom functions by combining the telecom communication contact method with the telecom usage. However, the terminology of communication contact method and usage is different depending on the API you're using. Though the terminology is different, the context of the labels is the same.

There are multiple types of telecom communication contact method, some of which are technologies that are being phased out over time, for example fax or textphone. 

Each telecom communication contact method is linked with a one-to-one mapping to a telecom usage. This shows many examples of usage contexts of legacy technologies that are being phased out over time, like an answering machine or pager.

Each address entry within the address collection belong to one of these classes.

For services using NHS Notify, PDS data is not used to send a letter to a single address type. Instead, it selects the most logical address available on the patient's record:

1. If there is a temporary address within 3 months of its business-effective "from" date (read more on business-effective dates), then it will use the temporary address.
2. If there is no temporary address within 3 months of its business-effective "from" on record but there is a correspondence address, then it will use the correspondence address. 
3. If there is no temporary address within 3 months of its business-effective "from" and there is no correspondence address, then it will use the home address. 
4. If there is no temporary address within 3 months of its business-effective "from", there is no correspondence address and there is no home address on record then it will not send the letter. 

Though PDS allows for free text in the address lines field, addresses are displayed using this structure:

• line 1 - premises ID and/or house name, for example Flat 1 or The Old Schoolhouse
• line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, for example 23 Mill Lane
• line 3 - dependent locality/village, locality (if present), for example Boxgrove
• line 4 - post town, for example Leeds
• line 5 - county (if present), for example West Yorkshire
• Postcode

Patients may not have a standard UK address and are still entitled to NHS healthcare services. A patient may not have a standard address because they: 

• are homeless
• have no fixed address
• are temporarily visiting the UK 
• are a migrant 

There are existing standards and guidance for how NHS services and practices should handle these patient: 

• Guidance on patient registration for GP practices (bma.org.uk)
• Patient Registrations | PCSE (england.nhs.uk)
• CQC guidance and regulation for health and social care providers, local authorities and integrated care systems
• GOV.UK NHS entitlements: migrant health guide

Most NHS services are free to patients who live in the UK permanently. If patients do not normally live in the UK, they may have to pay for hospital treatment. As such, a patient's address should match their residential status.

When an addresses is entered, there is no need to validate it. If your system gets an address with a non-standard format, we suggest using this structure:

• line 1 - premises ID and/or house name, e.g. Flat 1 
• line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g.  5 Avenue
• line 3 - dependent locality/village, locality (if present), e.g.  Anatole
• line 4 - post town, county (if present) e.g. 75007 Paris
• line 5 - country, e.g. France
• Postcode / zip code

International addresses have different formats, so not all lines of the address are needed and what each line contains may vary. It's important to note the country and the postcode (or zip code).

Where the address does not have a postcode or zip code, the address is given a pseudo-postcode.  These pseudo-postcodes begin with ZZ99. They are used:

• as a default for UK patients who have an unknown home address 
• for international patients to identify their home country

Patient records containing ZZ99 postcodes for the home address are deemed uncontactable by NHS services (including NHS Notify) because a letter cannot be sent to this address. 

Address for homeless and no fixed address

Patients with no fixed address or that are homeless should contact their GP to discuss their residential status. They should issue a temporary address type that the patient has access to. This may be a friend's address, a day centre, or their GP's address. 

If a patient has no fixed address, this should be recorded with the appropriate pseudo-postcode.

Address for temporary visitors and migrants

For overseas visitors and non-UK addresses, there is no technical validation on the address entered as each country's address format varies.

It's important to record the country and the postcode or zip code. Where it is not possible to enter a postcode or zip code, the address is given a pseudo-postcode that is specific to the country. For example, "ZZ99 6CZ" is the pseudo-postcode for India.

Structure of pseudo-postcodes

These pseudo-postcodes are only used when the patient has no UK address that they can access. Each pseudo-postcode reflects the context of residence in relation to the address of the patient. This is the string "ZZ99" plus a space followed by a numeric, then an alphabetical character, then a Z. 

A space can be inserted in the 8-character field. This differentiates between the inward and outward segments of the code. This enables full use to be made of Royal Mail postcode functionality.

The list of all UK pseudo-postcodes can be found at Office for National Statistics (ONS) data and Pseudo Country Postcode files.

Business-effective dates are used to define when the data is valid. This is date is often given by the patient or healthcare worker. 

• If the business-effective "from" date is in the past and the business-effective "to" date is in the future, the data is currently valid.
• If the business-effective "from" date is in the future and business-effective "to" date is in the future then the date is currently invalid.
• If the business-effective "from" date is in the past and business-effective "to" date is in the past then the contact detail is invalid.

If the service is patient-facing, healthcare worker-facing or restricted will change how the data is displayed.

System-effective  dates are used as an audit trail on data activity in PDS. PDS data points are either active or historic.

• If the system-effective "from" date is in the past and the system-effective "to" date is null, the data is currently active.
• If the system-effective "from" date is in the past and system-effective "to" date is in the past then the contact detail is historic.

Data that is historic or with a system-effective "to" date in the past must not be used to contact a patient and will not be displayed but may still be used to trace a patient.

Data retrieved from a PDS can be validated to ensure the data conforms to the correct standard schema. However, not every record on PDS is complete across the full schema. A record may also be incomplete as a response within the payload. Validation should be required on mandated fields like value, use and system (read more on telecom terminology for HL7 V3 API naming conventions). All other fields may not need validation to determine data usage.

Email address validation

To validate an email address, use the validatorjs library. You should ensure:

• the local part of the email (before the @) allows for up to 64 characters, including letters, digits, and specific special characters (' _ % + - ! /) and allowing for dot-separated sections
• the domain part of the email (after the @) must include at least one dot, with each section containing letters, digits, or hyphens
• the top-level domain (like .com, .org) must be at least two characters long.

If you cannot use the library, or want an extra front-end check, use this regular expression: /\b[A-Za-z0-9'_%+\-!\/]{1,64}(?:\.[A-Za-z0-9'_%+\-!\/]{1,64})*@([A-Za-z0-9\-]+\.)+[A-Za-z]{2,}\b

Mobile phone number validation

To validate a mobile phone, use the libphonenumber library. You should:

• allow any combination of digits (0-9), parentheses ( and ), and that these appears any number of times (the parenthesis opened must be closed and must contain non-zero number of digits)
• allow the input to start with an optional + or (
• allow for additional spaces, hyphens, dashes and brackets, and ensure they are able to accommodate country and area codes
• allow an option ";ext=", followed by more digits, with a minimum of 1 character and a maximum of 5 characters after
• ensure the input length is between 6 and 15 characters (not including the optional ";ext=" at the end)

Note that the functions to validate a mobile phone and landline differ in this library.

If you cannot use the library, or want an extra front-end check, use this regular expression: \s*(?:0|\+\s4\s4)\s7\s(?:[0-9]\s*){9}$. 

Landline number validation

To validate a landline number, use the libphonenumber library. You should:

• allow any combination of digits (0-9), parentheses ( and ), and that these appears any number of times (the parenthesis opened must be closed and must contain non-zero number of digits)
• allow the input to start with an optional +
• allow for additional spaces, hyphens, dashes and brackets, and be able to accommodate country and area codes
• allow an option ";ext=", followed by more digits, with a minimum of 1 character and a maximum of 5 characters after
• ensure the input length is between 6 and 15 characters (not including the optional ";ext=" at the end)

Note that the functions to validate a mobile phone and landline differ in this library.

If you cannot use the library, or want an extra front-end check, use this regular expression to validate UK landline numbers: ^+?0-9()(;ext=)?0-9$.

Address validation

To validate an address, use Ordnance Survey (OS) Places API. You should:

• ensure the postcode and first line of the address are mandatory at minimum
• ensure the address fields conform to the address structure
• ensure messaging is in place so the address does not contain any Personal Identifiable Data (PID) or information about how to access the address, for example no building access codes.

If it is a UK address, you can also use this regular expression to validate the postcode: /^[a-zA-Z]{1,2}[0-9][0-9A-Za-z]? ?[0-9][a-zA-Z]{2}$/

Ensure that the UK postcode:

• starts with 1 or 2 letters (either uppercase or lowercase)
• is followed by a single digit
• optionally followed by another digit or letter (uppercase or lowercase), but this part is non-greedy, so it will try to match as little as possible
• is followed by another single digit
• ends with exactly 2 characters, each of which can be a lowercase letter, an uppercase 'A', or a hyphen

If the patient has authenticated using NHS login the service should use the PDS FHIR API using patient access mode.

When tracing and updating data in PDS via an API, the NHS number of the subject must be obtained from NHS login's profile. This can be retrieved through scopes and claims.

NHS services that display or update patient contact details must comply with DCB3051 Identity Verification and Authentication Standard for Digital Health and Care Services, for example by onboarding to NHS login when authenticating to a service. Otherwise, the correct identity authentication and verification level should happen within the service journey. Currently, a service must achieve a verification level of high and an authentication level of high to display patient contact details from a PDS record. This is not the case when displaying NHS login details to a patient.

If the service team is using NHS login, services should only allow P9 verified patient with a high authentication level into the service (this means the user has a high vector of trust).

Read more about NHS login verification journeys.

NHS services that display or update patient contact details must mitigate against a session being hijacked to update a patient's PDS record. This can be through inactivity timeouts, where the service ends the current active session if there is 10 minutes of inactivity.  

Telecoms and addresses have multiple mappings of communication contact methods and types.

Though PDS can display different functions of address and telecom, patient-facing services do not need to display all the data to the end user. Service teams can decide which contact details best meet the needs of their users, while also considering the clinical perspective.

If the patient is P9 with a high vector of trust, a service can display the patient's contact details in plain text if:

• use NHS login at a high authentication level and a high verification level, or
• comply with DCB3051 Identity Verification and Authentication Standard for Digital Health and Care Services. 

Only active data points must be displayed in relation to today's date (read more on system-effective dates). Only valid data points must be displayed in relation to today's date (read more on business-effective dates). The service must display the latest data point based on the business-effective "from" date. When displaying contact details to a patient one datapoint must show for each combination of telecom communication method and usage or address type. If the patient has no active and valid contact detail on PDS then no contact detail should be shown to the patient.

If the patient is using NHS login and is P9 with a high vector of trust, the service can update that patient's contact details. Services cannot update patient contact details if they do not use NHS login at a high authentication level and a high verification level, or do not comply with DCB3051 Identity Verification and Authentication Standard for Digital Health and Care Services. 

Within PDS there must only be one active and valid telecom or address for each combination of telecom communication method and usage or address type on a patient's record at a once. This means the old address, as well as all inactive and invalid datapoints, must be removed from the patient's records. When a service using the PDS FHIR API submits the new datapoint to PDS via a PATCH operation, a delete operation must be performed on the old datapoint as well as the inactive and invalid datapoints on that record.

Healthcare worker-facing services should use one of these APIs when getting data from PDS:

• Personal Demographics Service (FHIR) API using healthcare worker access mode (read more on PDS FHIR API access modes)
• Personal Demographics Service (HL7 V3) API where a healthcare worker is strongly authenticated (read more on HL7 V3 security and authorisation)

Telecoms and addresses have multiple mappings of communication contact methods and types.

Though PDS can display multiple functions of address and telecom, services for healthcare workers do not need to display all the data to the end user. Service teams can decide which contact details best meet the needs of their users, while also considering the clinical perspective.

If the service has authenticated the end user and is using the API through a healthcare worker access mode, the service can display a patient's contact details in plain text. Services cannot display patient contact details in plain text if they do not use healthcare worker access mode.

Services can display an historic or invalid datapoint if it is the latest datapoint, based on business-effective "from" date. If the datapoint is historic, a label must be shown to mark this. If the datapoint is invalid then a label must be shown to mark this.

When displaying contact details to a patient, one datapoint must show for a combination of telecom communication method and usage or address type on a patient's record. If the patient does not have a contact detail on PDS then no contact detail should be returned to the patient.

If the service has authenticated the end user and is using the API through a healthcare worker access mode, the service can update the patient's contact details. Services cannot update patient contact details if they do not use healthcare worker access mode.

Within PDS there must only be one active and valid telecom or address for each combination of telecom communication method and usage or address type on a patient's record at a given time. This means the old address, as well as all inactive and invalid datapoints, must be removed from the patient's records. When a service using the PDS FHIR API submits the new datapoint to PDS via a PATCH operation, a delete operation must be performed on the old datapoint as well as the inactive and invalid datapoints on that record.

Unattended services should use the PDS FHIR API using restricted access mode.

This access mode is application-restricted, meaning authentication is performed on the calling application but not the end user. 

As there is no end user, it is the service team's responsibility to choose the contact details to use from the address types and combined telecom communication method and telecom usage. If the contact detail is not familiar to a patient, or controllable by a healthcare worker, there is a risk that the NHS will not use the contact detail and may cause confusion.

Unattended services that modify contact details should be reviewed on a case-by-case basis. Contact the API's onboarding team for information on how to modify contact details in restricted access mode.

It is the service team's responsibility to review data with an expired business-effective date.

For any temporary address or telecom fields that does not have a business-effective "to" date, the service should check that it's still within 3 months of the business-effective "from" date. If it has expired, try to use other contact methods.