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 patients (single result), Get patient details	Available in production (beta)
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.

Related APIs

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

Personal Demographics Service (SMSP) API - use this if you want to get PDS data without an authenticated end user (no smartcard required). It is, however, read-only and searches are limited to a single result.
Personal Demographics Service (HL7 V3) API - use this if you want to use functions that are not yet available on the FHIR API.

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

The following APIs are also related to this API:

Personal Demographics Service Notifications - FHIR API - use this to subscribe to be notified of a limited set of patient record changes, such as birth, death, change of address and change of GP. If you would like to see this list expanded, please tell us about your use case and vote here
Organisation Data Service FHIR API - use this to get full details for the organisations related to the patient, such as their registered GP or nominated pharmacy.

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:

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:

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

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:

Application-restricted RESTful API - signed JWT authentication

Healthcare worker access

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

The end user must be:

a healthcare worker
strongly authenticated, using either an NHS smartcard or a modern alternative
authorised, using national role-based access control (RBAC)

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:

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

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 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, or sensitive. 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:

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

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

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

{
  "resourceType" : "Patient",
  "id" : "9000000009",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/Id/nhs-number",
    "value" : "9000000009",
    "extension" : [ {
      "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus",
          "version" : "1.0.0",
          "code" : "01",
          "display" : "Number present and verified"
        } ]
      }
    } ]
  } ],
  "meta" : {
    "versionId" : "2",
    "security" : [ {
      "system" : "https://www.hl7.org/fhir/valueset-security-labels.html",
      "code" : "U",
      "display" : "unrestricted"
    } ]
  },
  "name" : [ {
    "id" : "123",
    "use" : "usual",
    "period" : {
      "start" : "2020-01-01",
      "end" : "2021-12-31"
    },
    "given" : [ "Jane" ],
    "family" : "Smith",
    "prefix" : [ "Mrs" ],
    "suffix" : [ "MBE" ]
  } ],
  "gender" : "female",
  "birthDate" : "2010-10-22",
  "multipleBirthInteger" : 1,
  "deceasedDateTime" : "2010-10-22T00:00:00+00:00",
  "generalPractitioner" : [ {
    "id" : "254406A3",
    "type" : "Organization",
    "identifier" : {
      "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
      "value" : "Y12345",
      "period" : {
        "start" : "2020-01-01",
        "end" : "2021-12-31"
      }
    }
  } ],
  "extension" : [ {
    "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y12345"
      }
    }
  }, {
    "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y23456"
      }
    }
  }, {
    "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y34567"
      }
    }
  }, {
    "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus",
    "extension" : [ {
      "url" : "deathNotificationStatus",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus",
          "version" : "1.0.0",
          "code" : "2",
          "display" : "Formal - death notice received from Registrar of Deaths"
        } ]
      }
    }, {
      "url" : "systemEffectiveDate",
      "valueDateTime" : "2010-10-22T00:00:00+00:00"
    } ]
  }, {
    "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication",
    "extension" : [ {
      "url" : "language",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage",
          "version" : "1.0.0",
          "code" : "fr",
          "display" : "French"
        } ]
      }
    }, {
      "url" : "interpreterRequired",
      "valueBoolean" : true
    } ]
  }, {
    "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference",
    "extension" : [ {
      "url" : "PreferredWrittenCommunicationFormat",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat",
          "code" : "12",
          "display" : "Braille"
        } ]
      }
    }, {
      "url" : "PreferredContactMethod",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod",
          "code" : "1",
          "display" : "Letter"
        } ]
      }
    }, {
      "url" : "PreferredContactTimes",
      "valueString" : "Not after 7pm"
    } ]
  }, {
    "url" : "http://hl7.org/fhir/StructureDefinition/patient-birthPlace",
    "valueAddress" : {
      "city" : "Manchester",
      "district" : "Greater Manchester",
      "country" : "GBR"
    }
  } ],
  "telecom" : [ {
    "id" : "789",
    "period" : {
      "start" : "2020-01-01",
      "end" : "2021-12-31"
    },
    "system" : "phone",
    "value" : "01632960587",
    "use" : "home"
  }, {
    "id" : "OC789",
    "period" : {
      "start" : "2020-01-01",
      "end" : "2021-12-31"
    },
    "system" : "other",
    "value" : "01632960587",
    "use" : "home",
    "extension" : [ {
      "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem",
      "valueCoding" : {
        "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem",
        "code" : "textphone",
        "display" : "Minicom (Textphone)"
      }
    } ]
  } ],
  "contact" : [ {
    "id" : "C123",
    "period" : {
      "start" : "2020-01-01",
      "end" : "2021-12-31"
    },
    "relationship" : [ {
      "coding" : [ {
        "system" : "http://terminology.hl7.org/CodeSystem/v2-0131",
        "code" : "C",
        "display" : "Emergency Contact"
      } ]
    } ],
    "telecom" : [ {
      "system" : "phone",
      "value" : "01632960587"
    } ]
  } ],
  "address" : [ {
    "id" : "456",
    "period" : {
      "start" : "2020-01-01",
      "end" : "2021-12-31"
    },
    "use" : "home",
    "line" : [ "1 Trevelyan Square", "Boar Lane", "City Centre", "Leeds", "West Yorkshire" ],
    "postalCode" : "LS1 6AE",
    "extension" : [ {
      "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey",
      "extension" : [ {
        "url" : "type",
        "valueCoding" : {
          "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType",
          "code" : "PAF"
        }
      }, {
        "url" : "value",
        "valueString" : "12345678"
      } ]
    } ]
  }, {
    "id" : "T456",
    "period" : {
      "start" : "2020-01-01",
      "end" : "2021-12-31"
    },
    "use" : "temp",
    "text" : "Student Accommodation",
    "line" : [ "1 Trevelyan Square", "Boar Lane", "City Centre", "Leeds", "West Yorkshire" ],
    "postalCode" : "LS1 6AE",
    "extension" : [ {
      "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey",
      "extension" : [ {
        "url" : "type",
        "valueCoding" : {
          "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType",
          "code" : "PAF"
        }
      }, {
        "url" : "value",
        "valueString" : "12345678"
      } ]
    } ]
  } ]
}

Schema

Name	Description
object
resourceType string read-only	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 read-only	Identifier and system of identification used for this Patient.
object	Max items: 1
system string url read-only	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 read-only	Status indicating if NHS number is present and verified.
url string read-only	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 read-only	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 read-only	The NHS Digital assigned version of the patient resource. Example: 2
security array read-only	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 Example: U
display string	Representation defined by the system. Allowed values: unrestricted, restricted, very restricted, redacted Example: unrestricted
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 read-only	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 Example: usual
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 Example: female
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 read-only	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 Example: home
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 Example: Student Accommodation
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 read-only	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 read-only required	Always 'type'. Default: type
valueCoding object required	URL of specification of address key format.
system string read-only required	URL of Code System that describes available Address Key formats. Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType
code string read-only required	Address Key system. Always 'PAF'. Default: PAF Example: PAF
object	Value of the address key.
url string read-only 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 read-only	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 Example: phone
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 Example: home
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 read-only	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 read-only	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 read-only	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 read-only	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 Example: phone
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 Example: home
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 read-only	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 read-only	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 read-only	Object identifier (OID) specific to the returned details - this should be return exactly the same in any update. Example: 254406A3
type string read-only	Type of Reference being returned. Example: Organization
identifier object required	Identifier and system of identification used for this Organisation.
system string read-only	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 read-only 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 read-only	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 read-only 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 read-only	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 read-only 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 read-only	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 read-only 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 read-only 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 Example: 2
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 Example: Formal - death notice received from Registrar of Deaths
object read-only	Wrapper object for death notification effective date.
url string read-only required	Key of this object. Always `systemEffectiveDate`. Allowed values: systemEffectiveDate Default: systemEffectiveDate
valueDateTime string date-time read-only 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 read-only 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 read-only 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 read-only	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 read-only 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 read-only 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 read-only 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 read-only	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 read-only 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 read-only	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 read-only 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 read-only 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	INVALID_VALUE	Cannot retrieve this result with NHS-login restricted access token.
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

{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "value",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "INVALID_RESOURCE_ID",
        "display" : "Resource Id is invalid"
      } ]
    }
  } ]
}

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 read-only	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 Example: error
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 Example: invalid
details object	Internal error code.
coding array
object read-only
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. 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, or sensitive. 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:

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

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

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.

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

{
  "resourceType" : "Bundle",
  "type" : "searchset",
  "timestamp" : "2019-12-25T12:00:00+00:00",
  "total" : 1,
  "entry" : [ {
    "fullUrl" : "https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009/RelatedPerson/507B7621",
    "resource" : {
      "id" : "507B7621",
      "resourceType" : "RelatedPerson",
      "patient" : {
        "type" : "Patient",
        "identifier" : {
          "system" : "https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient",
          "value" : "90000000009"
        },
        "reference" : "https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/90000000009"
      },
      "active" : true,
      "period" : {
        "start" : "2020-01-01",
        "end" : "2021-12-31"
      },
      "name" : [ {
        "use" : "usual",
        "period" : {
          "start" : "2020-01-01",
          "end" : "2021-12-31"
        },
        "given" : [ "Jane" ],
        "family" : "Smith",
        "prefix" : [ "Mrs" ],
        "suffix" : [ "MBE" ]
      } ],
      "relationship" : [ {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole",
          "code" : "Guardian",
          "display" : "Guardian of patient"
        } ]
      } ],
      "extension" : [ {
        "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator",
        "valueBoolean" : true
      }, {
        "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank",
        "valuePositiveInt" : 1
      }, {
        "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference",
        "extension" : [ {
          "url" : "PreferredWrittenCommunicationFormat",
          "valueCodeableConcept" : {
            "coding" : [ {
              "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat",
              "code" : "12",
              "display" : "Braille"
            } ]
          }
        }, {
          "url" : "PreferredContactMethod",
          "valueCodeableConcept" : {
            "coding" : [ {
              "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod",
              "code" : "1",
              "display" : "Letter"
            } ]
          }
        }, {
          "url" : "PreferredContactTimes",
          "valueString" : "Not after 7pm"
        } ]
      }, {
        "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication",
        "extension" : [ {
          "url" : "language",
          "valueCodeableConcept" : {
            "coding" : [ {
              "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage",
              "version" : "1.0.0",
              "code" : "fr",
              "display" : "French"
            } ]
          }
        }, {
          "url" : "interpreterRequired",
          "valueBoolean" : true
        } ]
      } ],
      "telecom" : [ {
        "period" : {
          "start" : "2020-01-01",
          "end" : "2021-12-31"
        },
        "system" : "phone",
        "value" : "01632960587",
        "use" : "home"
      } ],
      "address" : [ {
        "period" : {
          "start" : "2020-01-01",
          "end" : "2021-12-31"
        },
        "use" : "home",
        "line" : [ "1 Trevelyan Square", "Boar Lane", "City Centre", "Leeds", "West Yorkshire" ],
        "postalCode" : "LS1 6AE",
        "extension" : [ {
          "url" : "https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey",
          "extension" : [ {
            "url" : "type",
            "valueCoding" : {
              "system" : "https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType",
              "code" : "PAF"
            }
          }, {
            "url" : "value",
            "valueString" : "12345678"
          } ]
        } ]
      } ]
    }
  } ]
}

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 read-only	Unique object identifier for this name. Example: 507B7621
resourceType string read-only	FHIR resource type. Default: RelatedPerson
patient object required
type string read-only 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 read-only	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 read-only	URL for the FHIR Patient resource. Example: https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/90000000009
active boolean read-only	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 read-only	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 Example: usual
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 read-only	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 Example: home
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 Example: Student Accommodation
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 read-only	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 read-only required	Always 'type'. Default: type
valueCoding object required	URL of specification of address key format.
system string read-only required	URL of Code System that describes available Address Key formats. Default: https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType
code string read-only required	Address Key system. Always 'PAF'. Default: PAF Example: PAF
object	Value of the address key.
url string read-only 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 read-only	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 Example: phone
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 Example: home
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 read-only	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 read-only	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 read-only 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 read-only	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 read-only	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 read-only 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 read-only 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

Personal Demographics Service - FHIR API

Overview

Patients included in PDS

Access modes

Who can use this API

Who can access PDS records

Related APIs

API status and roadmap

Application-restricted access

Healthcare worker access

Patient access

Roadmap

Technology

Network access

Security and authorisation

Application-restricted access

Healthcare worker access

Patient access

Environments and testing

Sandbox testing

Integration testing

Production smoke testing

Onboarding

Endpoints

Get patient details

Overview

Superseded patients

Restricted patients

Sandbox test scenarios

Request

Path parameters

Headers

Response

HTTP status: 200

Headers

Body

Schema

HTTP status: 4XX

Body

Schema

Get a patient's related people

Overview

Restricted patients

Sandbox test scenarios

Request

Path parameters

Headers

Response

HTTP status: 200

Headers

Body

Schema