Skip to main content
Personal Demographics Service - FHIR API

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.

Overview

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
  • get patient details
  • update patient details
  • verify an NHS number for a patient

You cannot currently use this API to:

  • create a new record for a birth
  • receive birth notifications
  • create a record for a new patient
  • register a new patient at a GP Practice - instead, use NHAIS GP Links API

You can read and update the following data:

  • NHS number (read only)
  • name
  • gender
  • addresses and contact details
  • birth information
  • death information
  • registered GP
  • nominated pharmacy
  • dispensing doctor pharmacy
  • medical appliance supplier pharmacy
  • related people, such as next of kin (read only - update coming soon)

Patients included in PDS

Regardless of nationality, or where they live now, PDS includes all patients who have ever been registered with a GP practice, or treated by a health or care organisation (even as a visitor or migrant) in England, Wales, the Isle of Man, or in a UK Defence Medical Services unit anywhere in the world.

All patients in PDS have an NHS number which is unique. The 10-digit NHS number is used in England, Wales, the Isle of Man, Scotland and Northern Ireland, but not the Channel Islands. Scotland and Northern Ireland have their own distinct number ranges.

Access modes

This API has three access modes:

Access mode End user authentication Functions Availability
Application-restricted access None Search for a patient (single result). Get patient details. Available in production (stable)
Healthcare worker access NHS Care Identity Service 2 (NHS CIS2) using NHS smartcard or modern alternative Search for patients (multiple results). Get patient details. Update patient details. Available in production (beta)
Patient access NHS login Get own details. Update own details (limited). Available in integration environment (alpha)

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

Who can access PDS records

Health and care organisations in England and the Isle of Man can access PDS records. Legitimate direct care examples include NHS organisations delivering healthcare, local authorities delivering care, third sector and private sector health and care organisations, and developers delivering systems to health and care organisations.

Health and care organisations in Wales access their own version of PDS called the Welsh Demographics Service (WDS) which is connected to PDS behind the scenes.

Health and care organisations in Scotland, Northern Ireland and the Channel Islands access their own equivalents of PDS.

Patients who receive health and social care or make use of NHS services in England, Wales, the Isle of Man, Scotland, Northern Ireland and the Channel Islands.


The following APIs also give access to the Personal Demographics Service:

Once our roadmap is complete, the above APIs will become redundant.

The following APIs are also related to this API:


API status and roadmap

Application-restricted access

This access mode is stable:

  • you should strongly consider it as the primary choice for PDS integration
  • we do not make routine breaking changes, if it cannot be avoided, for example, for security reasons, we will give advance notice

Healthcare worker access

This access mode is in beta, meaning:

  • it is available in production
  • we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

Patient access

This access mode is in alpha, meaning:

  • it is available for testing in the integration environment, but not for production use
  • we might make breaking changes, but only if we cannot avoid it, and we will give advance notice

Roadmap

To see our roadmap, or to suggest, comment or vote on features for this API, see our interactive product backlog.

If you have any other queries, please contact us.


Technology

This API is RESTful.

It also conforms to the FHIR global standard for health care data exchange. Specifically, it is aligned with FHIR UK Core, which is built on FHIR Release 4.

You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular:

  • resource names are capitalised and singular, for example /Patient not /patients
  • array names are singular, for example line not lines for address lines
  • data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an extension object

There are libraries and SDKs available to help with FHIR API integration.


Network access

This API is available on the internet and, indirectly, on the Health and Social Care Network (HSCN).

To use this API with NHS smartcards you do need an HSCN connection, although internet-facing alternatives are available.

For more details see Network access for APIs.


Security and authorisation

Refer the table below to understand the recommended security pattern. The suggestions are based on who the users is, the functionality that they can access, authentication methods and ease of integration and onboarding.

User Functions User authentication Ease of integration and onboarding OAuth 2.0 flow and client authentication Recommended security pattern
Any or not present Search for a patient (single result). Get patient details. Not needed Easiest Client credentials with signed JWT Application restricted
Healthcare worker (except GP software user) Search for patients (multiple results). Get patient details. Update patient details. NHS CIS2 - smartcards or modern alternatives Easier Authorisation code with API key and secret NHS CIS2 - combined authentication and authorisation
Healthcare worker (including GP software user) Search for patients (multiple results). Get patient details. Update patient details. NHS CIS2 - smartcards or modern alternatives Easy Token exchange with signed JWT NHS CIS2 - separate authentication and authorisation
Patient Get own details. Update own details (limited). NHS login Easier Authorisation code with API key and secret NHS login - combined authentication and authorisation
Patient Get own details. Update own details (limited). NHS login Easy Token exchange with signed JWT NHS login - separate authentication and authorisation

Application-restricted access

This access mode is application-restricted, meaning we authenticate the calling application but not the end user.

You can use this access mode as follows:

  • unattended (end user not present), for example as part of a back end process to check NHS numbers for data flowing from one system to another
  • attended (end user present) - in which case, you must ensure the end user is authenticated and suitably authorised locally by the calling application

To use this access mode, use the following security pattern:

Healthcare worker access

This access mode is user-restricted, meaning an end user must be present, authenticated and authorised.

The end user must be:

To use this access mode, use one of the following security patterns:

Patient access

This access mode is user-restricted, meaning an end user must be present, authenticated and authorised.

The end user must be:

  • a patient who receives health and social care or makes use of NHS services
  • strongly authenticated, using NHS login

To use this access mode, use one of the following security patterns:


Environments and testing

Environment Base URL
Sandbox https://sandbox.api.service.nhs.uk/personal-demographics/FHIR/R4/
Integration test https://int.api.service.nhs.uk/personal-demographics/FHIR/R4/
Production https://api.service.nhs.uk/personal-demographics/FHIR/R4/

Sandbox testing

Our sandbox environment:

  • is for early developer testing
  • only covers a limited set of scenarios
  • is stateless, so does not actually persist any updates
  • is open access, so does not allow you to test authorisation

For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint.

Alternatively, you can try out the sandbox using our Postman collection:

Run in Postman

Integration testing

Our integration test environment:

  • is for formal integration testing
  • is stateful, so persists updates
  • includes authorisation, with options for user-restricted access (with or without smartcards and application-restricted access

For read-only testing, you can either use our PDS FHIR API test data packs or set up your own test data.

To test updating patient details, you must set up your own test data.

For more details see integration testing with our RESTful APIs.

Production smoke testing

You must not use real patient data for smoke testing in the production environment.

Rather, use our production test patient.


Onboarding

You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it’s worth planning well ahead.

To onboard for this API, follow the Supplier Conformance Assessment List (SCAL) process.

When following the general SCAL process steps, for this API you must do the following:

In step 1, to confirm your use case, you need to make a PDS access request, even if you already access PDS via another method.

In step 2, when requesting the SCAL, tell us which access mode you're using:

  • healthcare worker search and retrieve
  • healthcare worker update
  • application-restricted
  • patient access

In step 2, if using healthcare worker access mode, tell us which security pattern you are using:

  • NHS CIS2 - combined authentication and authorisation
  • NHS CIS2 - separate authentication and authorisation

In step 2, if using patient access mode, tell us which security pattern you are using:

  • NHS login - combined authentication and authorisation - available only upon request
  • NHS login - separate authentication and authorisation

In step 6, when implementing your clinical risk management process, you must review and integrate the PDS FHIR API hazard log into your own risk log. It's embedded within the PDS FHIR API tab in the SCAL.

In step 8, you need to review and complete the PDS FHIR API risk log to show that you have understood and mitigated the various risks. You might be asked to provide some evidence to prove that controls have been put in place. You can find the risk log embedded within the PDS FHIR API tab in the SCAL. This is separate from the clinical safety hazard log mentioned above.

In step 9, you must conduct penetration testing to CHECK standards.

In step 10, when you complete the Service Desk Registration Form, send it to api.management@nhs.net.

In step 11, submit your completed SCAL to api.management@nhs.net.

In step 14, to request production access, contact us at api.management@nhs.net.


Endpoints

Get patient details

get
/Patient/{id}

Overview

Use this endpoint to get patient details from PDS for a given NHS number.

You cannot get a patient's related people details, use the RelatedPerson endpoint instead.

Superseded patients

Some patients are marked as superseded, this means that for some reason the original resource is no longer valid and has been replaced with a different resource.

On retrieval of a superseded resource, the new resource is automatically returned in place of the requested resource. You can spot a superseded resource when the id is not the same as the one requested.

When retrieving a superseding resource you must update your system with the new resource and remove the superseded resource, ensuring that the same id does not exist against another resource in your system.

Restricted patients

Some patients are tagged as restricted and are sometimes known as sensitive patients. Restricted patients can be retrieved; however, location sensitive fields such as address, telecom and generalPractitioner are removed.

The restricted flag can be found in the data under meta/security on the patient resource.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

Scenario Request Response
Patient exists id=9000000009 HTTP Status 200 with patient data in response
Sensitive patient exists id=9000000025 HTTP Status 200 with patient data in response with the restricted data removed
Patient exists with minimal data id=9000000033 HTTP Status 200 with patient data in response, there will be very little data so can be used as an example of a patient with bad data quality
Patient does not exist id=9111231130 (or any other valid NHS number) HTTP Status 404 with problem description
Invalid NHS number id=9000000000 (or any invalid NHS number) HTTP Status 400 with problem description
Missing X-Request-ID id=9000000009 (or any other valid NHS number) HTTP Status 412 with problem description

You can try out the sandbox using the 'Try this API' feature on this page.

Alternatively, you can try out the sandbox using our Postman collection:

Run in Postman

Request

Path parameters
Name Description
id

String

The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number.

Example: 9000000009

Required
Headers
Name Description
Authorization

String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM

NHSD-Session-URID

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

This header is optional.

In Application-restricted access mode this header is ignored.

In Healthcare worker access mode if you send this header it must be valid for the logged-in user. See determine the user's role for guidance.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters.

Mirrored back in a response header.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

Response

HTTP status: 200

Information successfully returned.

Headers
Name Description
ETag

String

Record version identifier enclosed in quotes and preceded by 'W/'. For example, W/"2".

Corresponds to meta.versionId attribute in the patient resource body.

When you retrieve a patient resource, you get a version number for the resource (in the ETag response header and in the versionId field in the response). You must then pass the resource's version number in any update request (in the If-Match response header) made for the patient.

Pattern: /^W\/"[0-9]+"$/

Example: W/"2"

X-Correlation-Id

String

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

X-Request-Id

String

The X-Request-ID from the request header, if supplied, mirrored back.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string

FHIR resource type.

Default: Patient
id
string
required

The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number.

Pattern: ^\d{10}$
Example: 9000000009
identifier
array

Identifier and system of identification used for this Patient.

object
Max items: 1
system
string url

System identifier belongs to.

Default: https://fhir.nhs.uk/Id/nhs-number
value
string
required

The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number.

Pattern: ^\d{10}$
Example: 9000000009
extension
array

FHIR extensions.

object

Status indicating if NHS number is present and verified.

url
string

URL of the extension definition.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus
valueCodeableConcept
object

NHS Number Verification Status Indicator.

coding
array
required
Max items: 1
Min items: 1
object
system
string

URI of the coding system specification.

Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus
version
string

Version of the coding system in use.

Example: 1.0.0
code
string
required

Symbol in syntax defined by the system.

Example: 01
display
string

Representation defined by the system.

Example: Number present and verified
meta
object

Metadata about this resource.

versionId
string

The NHS Digital assigned version of the patient resource.

Example: 2
security
array

The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:

  • U - unrestricted. All available data is returned.
  • R - restricted. Any sensitive data around the patient's location, so address, generalPractitioner and telecom, are removed from the response.
  • V - very restricted. All patient data is removed from the response apart from id, identifier and meta fields. The gender field returns unknown regardless of actual gender.
  • REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.
Max items: 1
object
system
string

URI of the value set specification.

Example: https://www.hl7.org/fhir/valueset-security-labels.html
code
string

Code defined by the system value set.

Allowed values: U, R, V, REDACTED
display
string

Representation defined by the system.

Allowed values: unrestricted, restricted, very restricted, redacted
name
array

List of names associated with the patient.

When a patient tagged as very restricted is retrieved, all names are removed from the response.

Min items: 1
object
id
string

Unique object identifier for this name.

Example: 123
use
string
required

How this name should be used.

  • usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.
  • temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.
  • nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.
  • old - This name is no longer in use (or was never correct, but retained for records).
  • maiden - Name changed for Marriage. A name used prior to changing name because of marriage. This term is not gender specific. The use of this term does not imply any particular history for a person's name.

The following use codes are included in the name-use value set, but should not be used and is not be returned as part of a retrieval.

  • official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called "legal name".
  • anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).
Allowed values: usual, temp, nickname, old, maiden
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
given
array

Given names, including any middle names.

Each name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space. Subsequent names must be broken down into list items. For example, the input [Jane Marie Anne, Jo Adele] returns [Jane Marie Anne, Jo, Adele].

Max items: 5
Example: ["Jane Marie Anne","Jo","Adele"]
string
Max length: 35
Example: Jane
family
string
required

Family name (often called Surname).

Max length: 35
Example: Smith
prefix
array

Name prefixes, titles, and prenominals.

Example: ["Mrs"]
string
Example: Mrs
suffix
array

Name suffices and postnominals.

Example: ["MBE","PhD"]
string
Example: MBE
gender
string

Classification of the gender of a patient. The classification is phenotypical rather than genotypical, i.e. it does not provide codes for medical or scientific purposes. It is the administrative gender that the patient wishes to be known as. In some cases, this may not be the same as the patient’s registered birth gender, or their current clinical gender.

Allowed values: male, female, other, unknown
birthDate
string date

The date on which the patient was born or is officially deemed to have been born.

It is a date in the format yyyy-mm-dd. Due to data quality issues on a small number of patients yyyy-mm and yyyy format may also be returned.

When a patient tagged as very restricted is retrieved, birth date is removed from the response.

Example: 2010-10-22
multipleBirthInteger
integer

The order in which the patient was born, with 1 indicating the first or only birth in the sequence, 2 indicating the second birth in the sequence, 3 indicating the third, and so on up to 7.

There are two other valid values; 8 meaning Not applicable and 9 meaning Not known.

Maximum: 9 (inclusive)
Minimum: 1 (inclusive)
Example: 1
deceasedDateTime
string date-time

The date and time on which a person died or is officially deemed to have died, if applicable and known.

It is a datetime in the format yyyy-mm-ddTHH:MM:SS+HH:MM or yyyy-mm-dd. Due to data quality issues on a small number of patients yyyy-mm and yyyy format may also be returned.

When a patient tagged as very restricted is retrieved, death date is removed from the response.

Pattern: ^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T\d{2}:\d{2}:\d{2}\+\d{2}:\d{2})$|^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T\d{2}:\d{2}:\d{2})$|^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T\d{2}:\d{2}:\d{2}\+\d{2}:\d{2})$|^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))$
Example: 2010-10-22T00:00Z
address
array

List of addresses associated with the patient.

These are fully populated on a retrieval or a successful update, only the home address is returned on a search.

When a patient tagged as restricted or very restricted is retrieved, all addresses are removed from the response.

object

An address associated with the patient.

id
string

Unique system identifier for this address.

Example: 456
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
use
string
required

Purpose of this address:

  • home - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address
  • temp - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged
  • billing - an address used for correspondence purposes only
  • work - an office address. This can be returned due to legacy data but cannot be added or replaced on update

A patient should have no more than one current temp and/or billing address. However, historically this was constrained only by the integration requirements and was not enforced so theoretically more than one can exist for a patient when retrieving. Where multiple instances already exist for the patient it is not expected that local systems should manage those, but should choose the most appropriate one to maintain (e.g. by examining period dates).

A home address is the patient's main residential address and should normally be used for all clinical and demographic purposes, including clinical and appointment correspondence. However additionally, temp and billing addresses may be provided by a patient when there is a requirement to record an alternative location for the purposes of unbroken care. When sending correspondence to a patient:

  • a present and valid billing address may take precedence over home and temp addresses. A patient should have only a single current billing address. An address is considered 'valid' according to its period start and end dates.
  • if no current billing address is provided, a temp address may take precedence over the home address, again if it is valid according to its period start and end dates.
  • if there is no valid, current billing and/or temp address, the home address must be used.
Allowed values: home, work, temp, billing
text
string

Where a temp address is provided a descriptor text must be sent. The list of possible values are:

  • Second Home - a patient's second home
  • Student Accommodation - a patient's place of residence while at university
  • Respite Care Address - where the patient resides during respite care
  • Temporary Residence Address - where the patient resides for a specific period of time
  • Convalescence Home - the address for a patient during a period of recovery
  • Mobile Home - the address of a patient's mobile home, parked for a specific period of time, e.g. the address of a caravan park
  • Holiday Home - the address for a patient during a holiday

A patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.

Allowed values: Second Home, Student Accommodation, Respite Care Address, Temporary Residence Address, Convalescence Home, Mobile Home, Holiday Home
line
array

All lines of the address except the postal code.

Systems must apply the following formatting convention when adding or replacing addresses lines:

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

If any of the lines are blank, they are not returned due to FHIR conformance constraints.

Max items: 5
Example: ["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]
string
postalCode
string

Postal code of the address.

Example: LS1 6AE
extension
array

Postal Address File (PAF) key associated with this address formatted as a FHIR extension. Empty if no PAF key for the address is known, or an object specifying the code system of the address key and the value of the address key.

object

Unique identifier for an address.

url
string

URL of specification of the AddressKey extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey
extension
array

Specification of address key system and address key value. Contains exactly two items: one describing the code system the Address Key uses, and the other specifying the value of the Address Key.

Max items: 2
Min items: 2
anyOf
object

Coding system of the address key.

url
string
required

Always 'type'.

Default: type
valueCoding
object
required

URL of specification of address key format.

system
string
required

URL of Code System that describes available Address Key formats.

Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType
code
string
required

Address Key system. Always 'PAF'.

Default: PAF
Example: PAF
object

Value of the address key.

url
string
required

Always 'value'.

Default: value
Example: value
valueString
string
required

Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.

Pattern: ^[0-9]{8}$
Max length: 8
Min length: 8
Example: 12345678
telecom
array

List of contact points for the patient; for example, phone numbers or email addresses.

When a patient tagged as restricted or very restricted is retrieved, all contact points are removed from the response.

object

A contact point, such as a phone number or email address

id
string

Unique object identifier for this contact point.

Example: 789
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
system
string
required

Means of communication, such as phone or email.

Allowed values: phone, fax, email, other
value
string
required

Phone number, email address, or other identifier for use with contact system.

Example: 01632960587
use
string

Location associated with communication system.

Allowed values: home, work, temp, mobile
extension
array

Extension that is returned when the communication type is textphone. The only code returned is textphone, which means Minicom (Textphone).

The system is other when the extension is included.

Max items: 1
object

Wrapped object for other contact system details.

url
string

Definition of other contact system extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem
valueCoding
object

URL of specification of other contact systems.

system
string

URL of Code System that describes available contact relationships.

Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem
code
string

Coded value for the other contact system in place.

Example: textphone
display
string

Display-friendly representation of the other contact system code.

Example: Minicom (Textphone)
contact
array

A list of patient contacts. Only emergency contacts are returned and only emergency contacts should be added. Any other contacts should be added to the patients Related Person.

Patients designate here any contact number they desire to be used in case of an emergency. Note, while a patient may also desire to record various related persons telecom details, these do not separately allow for a concept of emergency contact; only ranking. See RelatedPerson endpoint.

When a patient tagged as restricted or very restricted is retrieved, all contacts are removed from the response.

object
Schema for a patient contact.
id
string
Example: C123
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
relationship
array
required

The contact relationship wrapper object that holds the details of the relationship to the patient.

This is only returned when an Emergency Contact number has been set on telecom. The only valid code is C, which means Emergency Contact.

Max items: 1
Min items: 1
object
coding
array
required

Exactly one contact relationship.

Max items: 1
Min items: 1
object
system
string url

URL of Code System that describes available contact relationships.

Default: http://terminology.hl7.org/CodeSystem/v2-0131
code
string
required

Coded value for contact relationship.

Example: C
display
string

Display-friendly representation of the contact relationship code.

Example: Emergency Contact
telecom
array
required

List of Telecom objects on the contact only contains system and value.

object

A contact point, such as a phone number or email address

id
string

Unique object identifier for this contact point.

Example: 789
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
system
string
required

Means of communication, such as phone or email.

Allowed values: phone, fax, email, other
value
string
required

Phone number, email address, or other identifier for use with contact system.

Example: 01632960587
use
string

Location associated with communication system.

Allowed values: home, work, temp, mobile
extension
array

Extension that is returned when the communication type is textphone. The only code returned is textphone, which means Minicom (Textphone).

The system is other when the extension is included.

Max items: 1
object

Wrapped object for other contact system details.

url
string

Definition of other contact system extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem
valueCoding
object

URL of specification of other contact systems.

system
string

URL of Code System that describes available contact relationships.

Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem
code
string

Coded value for the other contact system in place.

Example: textphone
display
string

Display-friendly representation of the other contact system code.

Example: Minicom (Textphone)
generalPractitioner
array

General Practice (not practitioner) with which the patient is, or was, registered. Always contains zero or one general practitioner object.

When a patient tagged as restricted or very restricted is retrieved, the General Practice is removed from the response.

Max items: 1
object

General practice (not practitioner) with which the patient is or was registered.

id
string

Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.

Example: 254406A3
type
string

Type of Reference being returned.

Example: Organization
identifier
object
required

Identifier and system of identification used for this Organisation.

system
string

URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.

Example: https://fhir.nhs.uk/Id/ods-organization-code
value
string
required

Organisation code for the registered general practice, as held in the Organisation Data Service.

Pattern: ^[0-9A-Z]+$
Example: Y12345
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
extension
array

Wrapper array for the patient's pharmacies, death notification status, communication details, contact preferences and place of birth; these are all FHIR extensions. Always contains zero or one of each pharmacy object, zero or one death notification status object, zero or one communication details object, zero or one contact preference and zero or one place of birth object.

When a patient tagged as restricted or very restricted is retrieved, the pharmacy and birth place extensions are removed from the response.

anyOf
object

Wrapper object for the patient's nominated pharmacy. This will only be populated on a retrieval and not a search.

url
string
required

URL of specification of UKCore-NominatedPharmacy FHIR extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy
valueReference
object
required

Reference to a pharmacy Organization resource.

identifier
object
required

Wrapper object for the patient's nominated pharmacy organisation code.

system
string

URL for the FHIR code system for the ODS organisation code.

Default: https://fhir.nhs.uk/Id/ods-organization-code
value
string
required

Organisation code for the nominated pharmacy, as held in the Organisation Data Service.

Pattern: ^[A-Za-z0-9]{3,10}$
Example: Y12345
object

Wrapper object for the patient's dispensing doctor. This will only be populated on a retrieval and not a search.

url
string
required

URL of specification of UKCore-DispensingDoctor FHIR extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization
valueReference
object
required

Reference to a GP practice pharmacy Organization resource.

identifier
object
required

Wrapper object for the patient's dispensing doctor organisation code.

system
string

URL for the FHIR code system for the ODS organisation code.

Default: https://fhir.nhs.uk/Id/ods-organization-code
value
string
required

Organisation code for the dispensing doctor, as held in the Organisation Data Service.

Pattern: ^[A-Za-z0-9]{3,10}$
Example: Y23456
object

Wrapper object for the patient's medical appliance supplier. This will only be populated on a retrieval and not a search.

url
string
required

URL of specification of UKCore-MedicalApplianceSupplier FHIR extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier
valueReference
object
required

Reference to medical appliance supplier pharmacy Organization resource.

identifier
object
required

Wrapper object for the patient's medical appliance supplier organisation code.

system
string

URL for the FHIR code system for the ODS organisation code.

Default: https://fhir.nhs.uk/Id/ods-organization-code
value
string
required

Organisation code for the medical appliance supplier, as held in the Organisation Data Service.

Pattern: ^[A-Za-z0-9]{3,10}$
Example: Y34567
object

Wrapper object for death notification details.

url
string
required

Definition of death notification extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus
extension
array
required

Array containing exactly one death notification status code object and exactly one effective date object.

Max items: 2
Min items: 1
oneOf
object

Wrapper object for death notification status code.

url
string
required

Key of this object. Always deathNotificationStatus.

Allowed values: deathNotificationStatus
Default: deathNotificationStatus
valueCodeableConcept
object
required

Death Notification Status.

coding
array
Max items: 1
Min items: 1
object
system
string
required

URI of the coding system specification.

Example: https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus
version
string

Version of the coding system in use.

Example: 1.0.0
code
string
required

Symbol, in syntax, defined by the system:

  • 1 - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust
  • 2 - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:
    • National Back Office using the Demographic Spine Application (DSA)
    • Office of National Statistics (ONS)
    • Maternity sites
  • U - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it
Allowed values: 1, 2, U
display
string

Representation defined by the system.

Allowed values: Informal - death notice received via an update from a local NHS Organisation such as GP or Trust, Formal - death notice received from Registrar of Deaths, Removed
object

Wrapper object for death notification effective date.

url
string
required

Key of this object. Always systemEffectiveDate.

Allowed values: systemEffectiveDate
Default: systemEffectiveDate
valueDateTime
string date-time
required

Date and time at which death notification status took effect.

Example: 2010-10-22T00:00Z
object

Wrapper object for communication details. This will only be populated on a retrieval and not a search.

url
string
required

Definition of communication extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication
extension
array
required

Definition of communication extension, The array must have two items, a valueCodeableConcept for the language and a valueBoolean for if an interpreter is required.

Max items: 2
Min items: 1
anyOf
object

Wrapper object for communication language.

url
string
required

Key of this object. Always language.

Allowed values: language
Default: language
valueCodeableConcept
object
required

Human language.

coding
array
required

Exactly one language code.

Max items: 1
Min items: 1
object
system
string

URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.

Example: https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage
version
string

Version of the language code system.

Example: 1.0.0
code
string
required

Language code based on ISO 639-1 standard plus extensions for braille, makaton and sign languages, which are:

  • q1 - Braille
  • q2 - American Sign Language
  • q3 - Australian Sign Language
  • q4 - British Sign Language
  • q5 - Makaton All valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.
Example: fr
display
string

Display-friendly representation of the language code (such as English). If there is a language code with no defined mapping, Unknown will be returned.

Example: French
object

Wrapper object for whether an interpreter is required.

url
string
required

Key of this object. Always interpreterRequired.

Allowed values: interpreterRequired
Default: interpreterRequired
valueBoolean
boolean
required

Whether an interpreter is required.

Example: true
object

Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.

url
string
required

Definition of the contact preference extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference
extension
array
required

Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.

Max items: 3
oneOf
object

Wrapper object for preferred written communication format.

url
string
required

Key of this object. Always PreferredWrittenCommunicationFormat.

Default: PreferredWrittenCommunicationFormat
valueCodeableConcept
object
required

Preferred Written Communication Format.

coding
array
required
Max items: 1
Min items: 1
object
system
string url

Definition of the preferred written communication extension.

Allowed values: https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat
Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat
code
string
required

A code to identify the preferred written communication format of a patient, contact or related person.

  • 11 - Large print
  • 12 - Braille
  • 13 - Audio tape
Example: 12
display
string

Display-friendly representation of the preferred written communication format code.

Example: Braille
object

Wrapper object for preferred contact method.

url
string
required

Key of this object. Always PreferredContactMethod.

Allowed values: PreferredContactMethod
Default: PreferredContactMethod
valueCodeableConcept
object
required

Preferred Contact Method.

coding
array
required
Max items: 1
Min items: 1
object
system
string url

Definition of the preferred contact method extension.

Allowed values: https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod
Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod
code
string
required

A code to identify to identify the preferred contact method of a patient, contact or related person.

  • 1 - Letter
  • 2 - Visit
  • 3 - Telephone
  • 4 - E-mail
  • 5 - Minicom (Textphone)
  • 6 - Telephone contact via proxy
  • 7 - Sign language
  • 8 - No Telephone contact
Example: 1
display
string

Display-friendly representation of the preferred contact method code.

Example: Letter
object

Wrapper object for preferred contact times.

url
string
required

Key of this object. Always PreferredContactTimes.

Allowed values: PreferredContactTimes
Default: PreferredContactTimes
valueString
string
required

A free-text description about the preferred contact times.

Maximum: 40 (inclusive)
Example: Not after 7pm
object

Wrapper object for place of birth details. This will not be returned on a restricted patient.

url
string
required

Definition of place of birth extension.

Allowed values: http://hl7.org/fhir/StructureDefinition/patient-birthPlace
Default: http://hl7.org/fhir/StructureDefinition/patient-birthPlace
valueAddress
object
required
city
string

Town or city of birth.

Example: Manchester
district
string

County or metropolitan district of birth.

Example: Greater Manchester
country
string

A coded value for a patient's country of birth.

From ISO 3166-1 plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.

UK Internal Codes:

  • 1 - England
  • 2 - Scotland
  • 3 - Wales
  • 4 - Northern Ireland
  • 7 - Sark
  • 9 - Alderney
  • 10 - Channel Islands
Example: GBR
HTTP status: 4XX

An error occurred as follows:

HTTP status Error code Description
400 INVALID_RESOURCE_ID Invalid NHS number.
400 UNSUPPORTED_SERVICE Missing NHS number.
400 MISSING_VALUE Missing header parameter. For details, see the diagnostics field.
400 INVALID_VALUE Invalid header parameter. For details, see the diagnostics field.
401 ACCESS_DENIED Access token missing, invalid or expired, or calling application not configured for this operation.
403 ACCESS_DENIED Patient cannot perform this action.
404 RESOURCE_NOT_FOUND Patient does not exist for given NHS number.
404 INVALIDATED_RESOURCE Patient did exist for given NHS number, but has been invalidated and not superseded by another NHS number.
408 UNABLE_TO_CALL_SERVICE The downstream domain processing has not completed within the configured timeout period.
429 TOO_MANY_REQUESTS You have exceeded your application's rate limit.
Body

Content type: application/fhir+json

Example

Schema

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission. There are a number of possible error codes that can be returned along with a more detailed description in the display field.

resourceType
string

FHIR Resource Type.

Default: OperationOutcome
issue
array

List of issues that have occurred.

Min items: 1
object
severity
string
required

Severity of the error.

Allowed values: fatal, error, warning, information
code
string
required

FHIR error code.

Allowed values: invalid, structure, required, value, invariant, security, login, unknown, expired, forbidden, suppressed, processing, not-supported, duplicate, multiple-matches, not-found, deleted, too-long, code-invalid, extension, too-costly, business-rule, conflict, transient, lock-error, no-store, exception, timeout, incomplete, throttled, informational
details
object

Internal error code.

coding
array
object
system
string

URI of the coding system specification.

Example: https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode
version
string

Version of the coding system in use.

Example: 1
code
string

Symbol in syntax defined by the system.

Example: INVALID_VALUE
display
string

Representation defined by the system.

Example: Provided value is invalid
diagnostics
string

Additional diagnostic information about the issue. This information is subject to change.

Example: Invalid value - 2019-01 in field 'birthDate'
expression
string

FHIRPath of element(s) related to the error.

Example: Patient.name.given
get
/Patient/{id}/RelatedPerson

Overview

Use this endpoint to get a patient's related people details from PDS for a given NHS number. This is a list of people who can be contacted, and how, regarding the patient. These details may be useful for a practitioner to get in contact with a next of kin or guardian.

Restricted patients

Some patients are tagged as restricted and are sometimes known as sensitive patients. Related people are not returned for a restricted patient and an empty bundle is returned.

If a related person only contains a patient reference reference, and when the patient is retrieved, it is restricted; location sensitive fields such as address and telecom are removed.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

Scenario Request Response
Multiple related people exists id=9000000009 HTTP Status 200 with related person data in a response Bundle
Single related person exists id=9000000017 HTTP Status 200 with related person data in a response Bundle
Related people do not exist id=9000000025 HTTP Status 404 with problem description
Missing X-Request-ID id=9000000009 (or any other valid NHS number) HTTP Status 412 with problem description

You can try out the sandbox using the 'Try this API' feature on this page.

Alternatively, you can try out the sandbox using our Postman collection:

Run in Postman

Request

Path parameters
Name Description
id

String

The patient's NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a valid NHS number.

Example: 9000000009

Required
Headers
Name Description
Authorization

String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM

NHSD-Session-URID

String

The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

This header is optional.

In Application-restricted access mode this header is ignored.

In Healthcare worker access mode if you send this header it must be valid for the logged-in user. See determine the user's role for guidance.

Pattern: /^[0-9]+$/

Example: 555254240100

X-Request-ID

String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.

Must be a universally unique identifier (UUID) (ideally version 4).

Mirrored back in a response header.

If you re-send a failed request, use the same value in this header.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

X-Correlation-ID

String

An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding . characters.

Mirrored back in a response header.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

Response

HTTP status: 200

Information successfully returned.

Headers
Name Description
ETag

String

Record version identifier enclosed in quotes and preceded by 'W/'. For example, W/"2".

Corresponds to meta.versionId attribute in the patient resource body.

When you retrieve a patient resource, you get a version number for the resource (in the ETag response header and in the versionId field in the response). You must then pass the resource's version number in any update request (in the If-Match response header) made for the patient.

Pattern: /^W\/"[0-9]+"$/

Example: W/"2"

X-Correlation-Id

String

The X-Correlation-ID from the request header, if supplied, mirrored back.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

X-Request-Id

String

The X-Request-ID from the request header, if supplied, mirrored back.

Pattern: /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/

Example: 60E0B220-8136-4CA5-AE46-1D97EF59D068

Body

Content type: application/fhir+json

Example

Schema

Name Description
object
resourceType
string

FHIR Resource Type.

Default: Bundle
type
string

FHIR Bundle Type.

Default: searchset
timestamp
string datetime

Time the search was performed.

Example: 2019-12-25T12:00:00+00:00
total
integer

Number of resources returned in search.

Example: 1
entry
array

A list of related people details attached to the patient.

object
fullUrl
string

Absolute URL of the resource described in this item.

Example: https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009/RelatedPerson/507B7621
resource
object
id
string

Unique object identifier for this name.

Example: 507B7621
resourceType
string

FHIR resource type.

Default: RelatedPerson
patient
object
required
type
string
required
Allowed values: Patient
Default: Patient
identifier
object

Identifier and system of identification used for this Patient.

This is an optional field as related person details are either a reference to another NHS number, or the details, such as name and adress, stored directly on the resource.

system
string url

URL for the Patient retrieval API.

Example: https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient
value
string

NHS number for the related person

Pattern: ^\d{10}$
Example: 90000000009
reference
string url

URL for the FHIR Patient resource.

Example: https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/90000000009
active
boolean
Default: true
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
name
array

List containing zero or one name associated with the related person.

This is an optional field as there may be a patient reference which can be used to retrieve any details about the related person.

If no patient reference is available name and address must be provided at the minimum.

Max items: 1
object
id
string

Unique object identifier for this name.

Example: 123
use
string
required

How this name should be used.

  • usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.
  • temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.
  • nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.
  • old - This name is no longer in use (or was never correct, but retained for records).
  • maiden - Name changed for Marriage. A name used prior to changing name because of marriage. This term is not gender specific. The use of this term does not imply any particular history for a person's name.

The following use codes are included in the name-use value set, but should not be used and is not be returned as part of a retrieval.

  • official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called "legal name".
  • anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).
Allowed values: usual, temp, nickname, old, maiden
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
given
array

Given names, including any middle names.

Each name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space. Subsequent names must be broken down into list items. For example, the input [Jane Marie Anne, Jo Adele] returns [Jane Marie Anne, Jo, Adele].

Max items: 5
Example: ["Jane Marie Anne","Jo","Adele"]
string
Max length: 35
Example: Jane
family
string
required

Family name (often called Surname).

Max length: 35
Example: Smith
prefix
array

Name prefixes, titles, and prenominals.

Example: ["Mrs"]
string
Example: Mrs
suffix
array

Name suffices and postnominals.

Example: ["MBE","PhD"]
string
Example: MBE
address
array

List containing zero or one address associated with the related person.

This is an optional field as there may be a patient reference which can be used to retrieve any details about the related person.

If no patient reference is available name and address must be provided at the minimum.

Max items: 1
object

An address associated with the patient.

id
string

Unique system identifier for this address.

Example: 456
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
use
string
required

Purpose of this address:

  • home - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address
  • temp - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged
  • billing - an address used for correspondence purposes only
  • work - an office address. This can be returned due to legacy data but cannot be added or replaced on update

A patient should have no more than one current temp and/or billing address. However, historically this was constrained only by the integration requirements and was not enforced so theoretically more than one can exist for a patient when retrieving. Where multiple instances already exist for the patient it is not expected that local systems should manage those, but should choose the most appropriate one to maintain (e.g. by examining period dates).

A home address is the patient's main residential address and should normally be used for all clinical and demographic purposes, including clinical and appointment correspondence. However additionally, temp and billing addresses may be provided by a patient when there is a requirement to record an alternative location for the purposes of unbroken care. When sending correspondence to a patient:

  • a present and valid billing address may take precedence over home and temp addresses. A patient should have only a single current billing address. An address is considered 'valid' according to its period start and end dates.
  • if no current billing address is provided, a temp address may take precedence over the home address, again if it is valid according to its period start and end dates.
  • if there is no valid, current billing and/or temp address, the home address must be used.
Allowed values: home, work, temp, billing
text
string

Where a temp address is provided a descriptor text must be sent. The list of possible values are:

  • Second Home - a patient's second home
  • Student Accommodation - a patient's place of residence while at university
  • Respite Care Address - where the patient resides during respite care
  • Temporary Residence Address - where the patient resides for a specific period of time
  • Convalescence Home - the address for a patient during a period of recovery
  • Mobile Home - the address of a patient's mobile home, parked for a specific period of time, e.g. the address of a caravan park
  • Holiday Home - the address for a patient during a holiday

A patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.

Allowed values: Second Home, Student Accommodation, Respite Care Address, Temporary Residence Address, Convalescence Home, Mobile Home, Holiday Home
line
array

All lines of the address except the postal code.

Systems must apply the following formatting convention when adding or replacing addresses lines:

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

If any of the lines are blank, they are not returned due to FHIR conformance constraints.

Max items: 5
Example: ["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]
string
postalCode
string

Postal code of the address.

Example: LS1 6AE
extension
array

Postal Address File (PAF) key associated with this address formatted as a FHIR extension. Empty if no PAF key for the address is known, or an object specifying the code system of the address key and the value of the address key.

object

Unique identifier for an address.

url
string

URL of specification of the AddressKey extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey
extension
array

Specification of address key system and address key value. Contains exactly two items: one describing the code system the Address Key uses, and the other specifying the value of the Address Key.

Max items: 2
Min items: 2
anyOf
object

Coding system of the address key.

url
string
required

Always 'type'.

Default: type
valueCoding
object
required

URL of specification of address key format.

system
string
required

URL of Code System that describes available Address Key formats.

Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType
code
string
required

Address Key system. Always 'PAF'.

Default: PAF
Example: PAF
object

Value of the address key.

url
string
required

Always 'value'.

Default: value
Example: value
valueString
string
required

Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.

Pattern: ^[0-9]{8}$
Max length: 8
Min length: 8
Example: 12345678
telecom
array

List containing zero to five contact methods associated with the related person.

This is an optional field as there may be a patient reference which can be used to retrieve any details about the related person.

Max items: 5
object

A contact point, such as a phone number or email address

id
string

Unique object identifier for this contact point.

Example: 789
period
object

Business effective period when name was, is, or will be in use.

start
string date
required

Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.

Example: 2020-01-01
end
string date

End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.

Example: 2021-12-31
system
string
required

Means of communication, such as phone or email.

Allowed values: phone, fax, email, other
value
string
required

Phone number, email address, or other identifier for use with contact system.

Example: 01632960587
use
string

Location associated with communication system.

Allowed values: home, work, temp, mobile
extension
array

Extension that is returned when the communication type is textphone. The only code returned is textphone, which means Minicom (Textphone).

The system is other when the extension is included.

Max items: 1
object

Wrapped object for other contact system details.

url
string

Definition of other contact system extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem
valueCoding
object

URL of specification of other contact systems.

system
string

URL of Code System that describes available contact relationships.

Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem
code
string

Coded value for the other contact system in place.

Example: textphone
display
string

Display-friendly representation of the other contact system code.

Example: Minicom (Textphone)
relationship
array
required

The relationship of the related person to the patient.

Max items: 1
Min items: 1
object
coding
array
required

Coded values for three relationship types:

  • Role
  • Type
  • Next-of-Kin

The codes used can be found at:

  • http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype
  • https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole

The allowed values for Role are:

  • Agent - Agent of patient
  • Guardian - Guardian of patient
  • Personal - Personal relationship with the patient

The allowed values for Type are:

  • SPS - spouse
  • DOMPART - domestic partner
  • PRN - parent
  • PRNFOST - foster parent
  • STPPRN - step parent
  • CHILD - child
  • MTH - mother
  • FTH - father
  • SIS - sister
  • BRO - brother
  • FAMMEMB - family member
  • ONESELF - self
  • N - Next-of-Kin
  • U - Unknown
  • PolygamousPartner - Polygamous Partner of patient
  • Dependant - Dependant of patient
  • NonDependant - Non Dependant of patient
  • ProxyContact - Proxy Contact for patient
  • ProxyCommunication - Proxy Communication for patient
  • ProxyContactCommunication - Proxy Contact and Communication for patient
  • Carer - Carer of patient
  • Guardian - Guardian of patient
  • NotSpecified - Not Specified

The allowed values for Next-of-Kin are:

  • N - Next-of-Kin

Role and Type are mandatory, so both should be present - however they both contain the Guardian code - so a single response is possible.

Next-of-Kin is optional and will be absent from the response when the related person is not the Next-of-Kin.

Max items: 3
Min items: 1
object
system
string url
required

URI of the coding system specification.

Allowed values: http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype, https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole
Default: https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole
code
string
required

Symbol in syntax defined by the system.

Example: Guardian
display
string

Human-friendly display representation defined by the system.

Example: Guardian of patient
extension
array

Wrapper array for copy correspondence, contact rank, contact preferences and communication details; these are all FHIR extensions. Always contains zero or one of each extension type.

anyOf
object

Flag indicating if this person should be copied in on any contact with the Patient. This will only be returned if the value is true and the person should be copied in on correspondence, otherwise it will be omitted.

url
string url

URL to FHIR Extension Specification.

Allowed values: https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator
Default: https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator
valueBoolean
boolean

Flag indicating if this person should be copied in on correspondence. This will only be returned if the value is true otherwise it will not be returned and can be assumed false

Example: true
object

Rank indicating order in which contacts should be tried.

url
string url

URL to FHIR Extension Specification.

Allowed values: https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank
Default: https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank
valuePositiveInt
integer

Rank expressed as positive integer (1 being the highest).

Maximum: 99 (inclusive)
Minimum: 1 (inclusive)
Example: 1
object

Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.

url
string
required

Definition of the contact preference extension.

Allowed values: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference
Default: https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference
extension
array
required

Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.

Max items: 3
oneOf
object

Wrapper object for preferred written communication format.

url
string
required

Key of this object. Always PreferredWrittenCommunicationFormat.

Default: PreferredWrittenCommunicationFormat
valueCodeableConcept
object
required

Preferred Written Communication Format.

coding
array
required
Max items: 1
Min items: 1
object
system
string url

Definition of the preferred written communication extension.

Allowed values: https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat
Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat
code
string
required