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 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 and NHS number.

You can:

  • search for patients
  • get patient details
  • update patient details

You cannot currently use this API to:

  • check that you have the right NHS number for a patient (but you can achieve this indirectly using search for patient or get patient details)
  • 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 Identity (NHS smartcard or modern alternative) Search for patients (multiple results), Get patient details, Update patient details Available in production (beta)
Citizen access NHS login Get own details, Update own details (limited) Not available yet, see backlog for details

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.

Related APIs

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 in beta, meaning:

  • we might make breaking changes, but only if we cannot avoid it, and we'll 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'll give advance notice

Citizen access

This access mode is not available yet.

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 don’t 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:

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:

Citizen access

This access mode is not available yet.

For more details, see our interactive product backlog.

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 smartcard) 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 SCAL process, note that:

  • In step 1: to confirm your use case for this API, 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 (a) which access mode you're using: (i) healthcare worker search and retrieve, (ii) healthcare worker update or (iii) application-restricted; (b) for healthcare worker access, which security pattern you are using: (i) combined authentication and authorisation or (ii) 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}
Try this API

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

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

For more details, see determine the user’s role.

Required for user-restricted access but optional for application-restricted access and for sandbox environment.

Pattern: /^[0-9]+$/
Example: 555021935107
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.

Required in all environments except sandbox.

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
{
  "resourceType" : "Patient",
  "id" : "9000000009",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/Id/nhs-number",
    "value" : "9000000009",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NominatedPharmacy",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y12345"
      }
    }
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y23456"
      }
    }
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y34567"
      }
    }
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-DeathNotificationStatus",
    "extension" : [ {
      "url" : "deathNotificationStatus",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSCommunication",
    "extension" : [ {
      "url" : "language",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-HumanLanguage",
          "version" : "1.0.0",
          "code" : "fr",
          "display" : "French"
        } ]
      }
    }, {
      "url" : "interpreterRequired",
      "valueBoolean" : true
    } ]
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactPreference",
    "extension" : [ {
      "url" : "PreferredWrittenCommunicationFormat",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-PreferredWrittenCommunicationFormat",
          "code" : "12",
          "display" : "Braille"
        } ]
      }
    }, {
      "url" : "PreferredContactMethod",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-OtherContactSystem",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey",
      "extension" : [ {
        "url" : "type",
        "valueCoding" : {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey",
      "extension" : [ {
        "url" : "type",
        "valueCoding" : {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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 should be a separate item in the list and should not contain spaces; for example Jane Adele should be broken down into two list items Jane and Adele.

Max items: 5
Example: ["Jane","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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-OtherContactSystem
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-OtherContactSystem
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NominatedPharmacy
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-DeathNotificationStatus
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSCommunication
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactPreference
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/CodeSystem/UKCore-PreferredWrittenCommunicationFormat
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/CodeSystem/UKCore-PreferredContactMethod
Default: https://fhir.nhs.uk/R4/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.
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 For a synchronous request, the downstream domain processing has not completed within the configured timeout period.
412 PRECONDITION_FAILED Problem with request. For details, see the diagnostics field.
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 a patient's related people

get
/Patient/{id}/RelatedPerson
Try this API

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

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

For more details, see determine the user’s role.

Required for user-restricted access but optional for application-restricted access and for sandbox environment.

Pattern: /^[0-9]+$/
Example: 555021935107
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.

Required in all environments except sandbox.

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
{
  "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.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactPreference",
        "extension" : [ {
          "url" : "PreferredWrittenCommunicationFormat",
          "valueCodeableConcept" : {
            "coding" : [ {
              "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-PreferredWrittenCommunicationFormat",
              "code" : "12",
              "display" : "Braille"
            } ]
          }
        }, {
          "url" : "PreferredContactMethod",
          "valueCodeableConcept" : {
            "coding" : [ {
              "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-PreferredContactMethod",
              "code" : "1",
              "display" : "Letter"
            } ]
          }
        }, {
          "url" : "PreferredContactTimes",
          "valueString" : "Not after 7pm"
        } ]
      }, {
        "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSCommunication",
        "extension" : [ {
          "url" : "language",
          "valueCodeableConcept" : {
            "coding" : [ {
              "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey",
          "extension" : [ {
            "url" : "type",
            "valueCoding" : {
              "system" : "https://fhir.nhs.uk/R4/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 should be a separate item in the list and should not contain spaces; for example Jane Adele should be broken down into two list items Jane and Adele.

Max items: 5
Example: ["Jane","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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-OtherContactSystem
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactPreference
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/CodeSystem/UKCore-PreferredWrittenCommunicationFormat
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/CodeSystem/UKCore-PreferredContactMethod
Default: https://fhir.nhs.uk/R4/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 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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSCommunication
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/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
HTTP status: 4XX
An error occurred as follows:

HTTP status Error code Description
400 INVALID_RESOURCE_ID Invalid 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.
404 RESOURCE_NOT_FOUND No related people exist for given NHS number.
404 INVALIDATED_RESOURCE Patient record for given NHS number has been invalidated and not superseded by another NHS number.
408 UNABLE_TO_CALL_SERVICE For a synchronous request, the downstream domain processing has not completed within the configured timeout period.
412 PRECONDITION_FAILED Problem with request. For details, see the diagnostics field.
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

Poll for the result of an update

get
/_poll/{message_id}
Try this API

Overview

Use this endpoint to poll for the outcome of an updated patient record.

When updating resources the request is dealt with in an asynchronous manner.

Once the initial request is accepted a 202 response is returned with a Content-Location header, use this location to poll for the outcome. It is in the form /_poll/<message id>.

Requests should be sent to the polling endpoint until a 202 response is no longer returned and the response is dealt with appropriately.

Polls should be done at a reasonable frequency to avoid excess traffic; the Retry-After header provides the time to wait in milliseconds between polls, although polling with a larger gap is also allowed. Retrieval of the outcome does not occur any faster by polling more frequently. The server simply returns a cached response.

Sandbox test scenarios

You can test the following scenarios in our sandbox environment:

Scenario Request Response
Perform a valid patch request and use the content-location message_id whatever was in update accepted response HTTP Status 200 with updated patient data
Polling message ID when update is not yet complete message_id=20200522091633363041_000001 HTTP Status 202 with no data
Polling message ID not found message_id=20200522091633363041_000002 HTTP Status 404 with operation outcome body

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
message_id
String
The message ID of the accepted update that needs to be submitted to confirm the resource a successfully updated.
Example: 20200522091633363041_000001A
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).

For more details, see determine the user’s role.

Required for user-restricted access but optional for application-restricted access and for sandbox environment.

Pattern: /^[0-9]+$/
Example: 555021935107
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
Patient updated.
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
{
  "resourceType" : "Patient",
  "id" : "9000000009",
  "identifier" : [ {
    "system" : "https://fhir.nhs.uk/Id/nhs-number",
    "value" : "9000000009",
    "extension" : [ {
      "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NominatedPharmacy",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y12345"
      }
    }
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y23456"
      }
    }
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier",
    "valueReference" : {
      "identifier" : {
        "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
        "value" : "Y34567"
      }
    }
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-DeathNotificationStatus",
    "extension" : [ {
      "url" : "deathNotificationStatus",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSCommunication",
    "extension" : [ {
      "url" : "language",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-HumanLanguage",
          "version" : "1.0.0",
          "code" : "fr",
          "display" : "French"
        } ]
      }
    }, {
      "url" : "interpreterRequired",
      "valueBoolean" : true
    } ]
  }, {
    "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactPreference",
    "extension" : [ {
      "url" : "PreferredWrittenCommunicationFormat",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-PreferredWrittenCommunicationFormat",
          "code" : "12",
          "display" : "Braille"
        } ]
      }
    }, {
      "url" : "PreferredContactMethod",
      "valueCodeableConcept" : {
        "coding" : [ {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-OtherContactSystem",
      "valueCoding" : {
        "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey",
      "extension" : [ {
        "url" : "type",
        "valueCoding" : {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey",
      "extension" : [ {
        "url" : "type",
        "valueCoding" : {
          "system" : "https://fhir.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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 should be a separate item in the list and should not contain spaces; for example Jane Adele should be broken down into two list items Jane and Adele.

Max items: 5
Example: ["Jane","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.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.nhs.uk/R4/StructureDefinition/Extension-UKCore-OtherContactSystem
Default: https://fhir.nhs.uk/R4/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.nhs.uk/R4/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.