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

This API has three access modes:

Access mode End user authentication Functions Availability
Healthcare professional access NHS Identity (NHS smartcard or modern alternative) Search for patients (multiple results), Get patient details, Update patient details Available in production (beta)
Application-restricted access None Search for patients (single result), Get patient details Available for testing (alpha)
Citizen access NHS login Get own details, Update own details (limited) Not available yet, see backlog for details

Legal use

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

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

Healthcare professional access

This access mode is in beta, meaning:

  • we might make breaking changes, but only if we can't avoid it, and we'll give advance notice
  • we can't guarantee availability or performance

Application-restricted access

This access mode is in alpha, meaning:

  • it is available for testing but not yet for production use
  • we might make breaking changes

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

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 (see below) you do need an HSCN connection, although internet-facing alternatives are available.

For more details see Network access for APIs.

Security and authorisation

Healthcare professional access

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

The end user must be:

  • a healthcare professional
  • strongly authenticated, using either an NHS smartcard or a modern alternative

The API uses OAuth 2.0 to authorise the calling system.

It supports the following security patterns:

In this access mode, all endpoints are fully available.

In addition, the end user must be authorised to perform the various activities.

The API itself does not perform any authorisation checks. Rather, the calling application must perform them. The authorisation rules are specified in our national Role Based Access Control (RBAC) database.

For more details, contact us.

Application-restricted access

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

In particular, we use following security pattern:

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

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/
Integration test https://int.api.service.nhs.uk/personal-demographics/
Production https://api.service.nhs.uk/personal-demographics/

Sandbox testing

Our sandbox environment:

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

For more details on sandbox testing, 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

Download Postman client

If you don’t have it, you can download Postman here.

Click on the download button in the top right corner and follow the instructions.

Download our collection

If you already have the Postman client installed - click onto our postman collection (button above) - then click onto the ‘Postman for Windows’ or ‘Postman for Mac’ version - and click Open when prompted.

Postman client should then open showing our Patient Demographics Sandbox.

If you have already downloaded the Sandbox collection from one of our other endpoints, found under the PDS FHIR API pages, you don't have to download it again as the same collection covers all endpoints.

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.

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 6: when implementing your clinical risk management process, you must review and integrate the PDS FHIR API hazard log into your own risk log. You’ll find it 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’ll 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.

Endpoint: Patients

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 will be automatically returned in place of the requested resource. You will be able to 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 will be 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 doesn't 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

Download Postman client

If you don’t have it, you can download Postman here.

Click on the download button in the top right corner and follow the instructions.

Download our collection

If you already have the Postman client installed - click onto our postman collection (button above) - then click onto the ‘Postman for Windows’ or ‘Postman for Mac’ version - and click Open when prompted.

Postman client should then open showing our Patient Demographics Sandbox.

If you have already downloaded the Sandbox collection from one of our other endpoints, found under the PDS FHIR API pages, you don't have to download it again as the same collection covers all endpoints.


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
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. Also optional in sandbox.

Pattern: /^[0-9]+$/
Example: 555021935107
Authorization
String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
X-Correlation-ID
String

A globally unique identifier (GUID) for the request, which we use to trace the request if you contact our helpdesk.

Mirrored back in a response header.

Avoid . characters.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Request-ID
String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests.

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

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

Mirrored back in a response 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

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"

Body

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

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object
resourceType
string
read-only
FHIR resource type.
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.
Pattern: ^\d{10}$
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.
value
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.
Pattern: ^\d{10}$
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.
valueCodeableConcept
object
NHS Number Verification Status Indicator.
coding
array
Max items: 1
Min items: 1
object
system
string
read-only
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
meta
object
Metadata about this resource.
versionId
string
read-only
The NHS Digital assigned version of the patient resource.
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 will be returned.
  • R - restricted. Any sensitive data around the patient's location, so address, generalPractitioner and telecom, will be removed from the response.
  • V - very restricted. All patient data will be removed from the response apart from id, identifier and meta fields. The gender field will return unknown regardless of actual gender.
  • REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code will never be returned; you will 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.
code
string
Code defined by the system value set.
display
string
Representation defined by the system.
name
array

List of names associated with the patient.

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

Min items: 1
object
id
string
read-only
Unique object identifier for this name.
use
string

How this name should be used.

  • usual - Known as, conventional or the one patient normally uses. A patient will always have 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 will 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).
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
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
string
Max length: 35
family
string
Family name (often called Surname).
Max length: 35
prefix
array
Name prefixes, titles, and prenominals.
string
suffix
array
Name suffices and postnominals.
string
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.
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 will be removed from the response.
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)
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 will be 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]))$
address
array

List of addresses associated with the patient.

This will only be fully populated on a retrieval, only a the home address will be returned on a search.

When a patient tagged as restricted or very restricted is retrieved, all addresses will be removed from the response.
object
An address associated with the patient.
id
string
read-only
Unique system identifier for this address.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
use
string

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.
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 will not appear on the PDS, but the address used for it may.
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 will not be returned due to FHIR conformance constraints.

Max items: 5
string
postalCode
string
Postal code of the address.
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.
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
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 will be 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.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
system
string
Means of communication, such as phone or email.
value
string
Phone number, email address, or other identifier for use with contact system.
use
string
Location associated with communication system.
extension
array

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

The system will only ever be 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.
valueCoding
object
URL of specification of other contact systems.
system
string
read-only
URL of Code System that describes available contact relationships.
code
string
Coded value for the other contact system in place.
display
string
Display-friendly representation of the other contact system code.
contact
array

A list of patient contacts. Only emergency contacts will be 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 will be removed from the response.
object
Schema for a patient contact.
id
string
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
relationship
array

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

This will only return 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
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.
code
string
Coded value for contact relationship.
display
string
Display-friendly representation of the contact relationship code.
telecom
array
List of Telecom objects on the contact will only contain 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.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
system
string
Means of communication, such as phone or email.
value
string
Phone number, email address, or other identifier for use with contact system.
use
string
Location associated with communication system.
extension
array

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

The system will only ever be 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.
valueCoding
object
URL of specification of other contact systems.
system
string
read-only
URL of Code System that describes available contact relationships.
code
string
Coded value for the other contact system in place.
display
string
Display-friendly representation of the other contact system code.
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 will be 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.
type
string
read-only
Type of Reference being returned.
identifier
object
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.
value
string
Organisation code for the registered general practice, as held in the Organisation Data Service.
Pattern: ^[0-9A-Z]+$
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
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 will be removed from the response.

HTTP status: 400

Invalid NHS number supplied.

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

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

HTTP status: 404

Patient not found.

Body

Content type: application/fhir+json
Example
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "not-found",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "RESOURCE_NOT_FOUND",
        "display" : "Resource not found"
      } ]
    }
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

Search for a patient

get

/Patient
Try this API

Overview

Use this endpoint to search for a patient in PDS.

You can search using a combination of:

  • given name
  • family name
  • gender
  • postcode
  • date of birth (range)
  • date of death (range)
  • registered GP practice

The behaviour of this endpoint depends on which access mode you are using:

Access mode Behaviour restrictions
Healthcare professional access Full behaviour available
Application-restricted access Limited to a single unique result
Citizen access Not yet available

Matching rules

Search parameters are not case sensitive.

Spaces in postcodes do not need to match exactly, for example LS116AD will match LS11 6AD, however including spaces will also work.

For date of birth and date of death, you can search for an exact date or for a range of dates.

You can use wildcards in given name and family name. Wildcards must start with at least two characters; for example, Br* is valid, but *cDougal is not. Multiple wildcards are allowed; for example, Br*w* will match Brown and Brower. Be sure that any wildcards are encoded before sending the request. An encoded wildcard is %2A; for example, Br%2A is valid.

You can request a fuzzy search using the _fuzzy-match query parameter. This will:

  • match common homophones, such as Smith and Smythe, using the Soundex algorithm
  • check for transposed names, such as Adam Thomas and Thomas Adam

Wildcards cannot be used with a fuzzy search.

Search parameter options

For a non-fuzzy search (_fuzzy-match=false), the minimum set of search parameters is:

  • family name - but it can include wildcards
  • gender
  • date of birth - but it can be a range

For a fuzzy search (_fuzzy-match=true), use one of the following search parameter combinations:

  • given name, family name and date of birth
  • family name, date of birth, gender and postcode
  • given name, date of birth, gender and postcode

If you include the date of death or registered GP Practice query parameters for a fuzzy search, they will not be used as part of the search. However they will affect the patient's matching score, meaning a mismatch will reduce the returned score.

If you use an invalid combination of query parameters, you will get an INVALID_COMBINATION error.

Historic data search

By default the endpoint only searches current information. You can search historic information, such as previous names or addresses using the _history query parameter.

You cannot perform a fuzzy search on historic information.

Scoring

Every matched patient in the result list includes a score to indicate how closely the patient matched the search parameters.

A score of 1.0 indicates an exact match. A score of less than 1.0 indicates a partial match.

The result list is sorted in descending score order - best match first.

Use the _exact-match query parameter to return exact matches only - where the score is 1.0.

Restricted patients

Some patients are tagged as restricted, or sensitive. When performing a search, restricted patients can be returned; however, location sensitive fields such as address, telecom, contact and generalPractitioner will be removed.

If address-postcode or general-practitioner are included in the search parameters, no restricted patients will be returned even if a match is identified.

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

Number of results returned

Healthcare professional access mode

By default, the endpoint will return a maximum of 50 results.

If there are more than 50 matching patients, the endpoint will return no results and the error response TOO_MANY_MATCHES. You can further limit the number of results using the _max-results query parameter. You can request a single, exact match using _exact-match=true and _max-results=1.

Application-restricted access mode

The endpoint will only return one result. If there is more than one matching patient, the endpoint will return no results and the error response TOO_MANY_MATCHES.

Patient data returned

The patient data returned on a search is not the full set of data that is returned on a retrieval. The following data is included:

  • NHS Number
  • name
  • gender
  • all birth information, apart from place of birth
  • death information
  • home address
  • contact details
  • registered GP
  • restricted patient flag

The following data is excluded:

  • place of birth
  • all addresses apart from home address
  • pharmacy details
  • communication details
  • contact preferences

Clinical safety and privacy

This endpoint can return multiple matching patients for a given search, including partial matches.

You should ensure that you design, build and test your software to minimise these risks:

  • an end user selects the wrong patient from the results presented, so there is a risk of clinical harm; for example due to retrieval of the wrong medical data
  • the end user has access to patients’ personal data, so there is a risk to patient privacy

In particular, it is almost certainly a good idea to display search results in descending score order - best match first.

Sandbox testing

You can test the following scenarios in our sandbox environment:

Scenario Request Response
Basic search family=Smith, gender=female, birthdate=eq2010-10-22 HTTP Status 200 with single search result.
Wildcard search family=Sm*, gender=female, birthdate=eq2010-10-22 HTTP Status 200 with search result of two.
Search with limited results family=Sm*, gender=female, birthdate=eq2010-10-22, _max-results=2 HTTP Status 200 with search result of two.
Search with date range family=Smith, gender=female, birthdate=ge2010-10-21, birthdate=le2010-10-23 HTTP Status 200 with single search result.
Fuzzy search family=Smith, given=Jane gender=female, birthdate=eq2010-10-22, _fuzzy-match=true HTTP Status 200 with single search result.
Restricted patient search family=Smythe, given=Janet gender=female, birthdate=eq2005-06-16 HTTP Status 200 with single search result with restricted data omitted.
Unsuccessful search Any other valid search query parameters HTTP Status 200 with no search results
Invalid date format birthdate or death-date query parameters with values not in format YYYY-MM-DD HTTP Status 400 with problem description
Too few search parameters Any invalid combination of query parameters 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

Download Postman client

If you don’t have it, you can download Postman here.

Click on the download button in the top right corner and follow the instructions.

Download our collection

If you already have the Postman client installed - click onto our postman collection (button above) - then click onto the ‘Postman for Windows’ or ‘Postman for Mac’ version - and click Open when prompted.

Postman client should then open showing our Patient Demographics Sandbox.

If you have already downloaded the Sandbox collection from one of our other endpoints, found under the PDS FHIR API pages, you don't have to download it again as the same collection covers all endpoints.


Request

Headers

Name Description
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. Also optional in sandbox.

Pattern: /^[0-9]+$/
Example: 555021935107
Authorization
String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
X-Correlation-ID
String

A globally unique identifier (GUID) for the request, which we use to trace the request if you contact our helpdesk.

Mirrored back in a response header.

Avoid . characters.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Request-ID
String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests.

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

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

Mirrored back in a response 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

Query parameters

Name Description
_exact-match
Boolean
Default value: false
The search only returns results where the score field is 1.0.
Example: true
_history
Boolean
Default value: false
The search looks for matches in historic information such as previous names and addresses.
Example: true
_fuzzy-match
Boolean
Default value: false
A fuzzy search is performed, including checks for homophones and transposed names.
Example: true
_max-results
Integer (int32)
The maximum number of matching patients to return. For user-restricted access, this must be between 1 and 50, and the default is 50. For application-restricted access, this must be 1, and the default is 1. If too many patients match the search criteria, the API returns a TOO_MANY_MATCHES error.
Example: 1
family
String

The patient's family name (surname).

Must be URL encoded. For example a space must be represented by either %20 or +.

Examples
Will also match Smythe if `_fuzzy-match` is specified.
Smith
Wildcards must contain at least two characters, this will match Smith, Smythe
Sm*t*
given
String

The patient's given name.

Must be URL encoded. For example a space must be represented by either %20 or +.

Example: Jane
gender
String
Gender with which the patient most strongly identifies.
Allowed values: male, female, other, unknown
Example: female
birthdate
array[String]
Date of birth in the format <eq|ge|le>yyyy-mm-dd. To specify a range, use birthdate=geyyyy-mm-dd&birthdate=leyyyy-mm-dd.
Examples
Exact match date
eq2010-10-22
Greater than or equals match, which matches 2010-10-22 or 2010-10-23
ge2010-10-22
Less than or equals match, which matches 2010-10-22 or 2010-10-21
le2010-10-22
death-date
date (date)
Date of death in the format <eq|ge|le>yyyy-mm-dd. To specify a range, use death-date=geyyyy-mm-dd&death-date=leyyyy-mm-dd.
Examples
Exact match date
eq2010-10-22
Greater than or equals match which matches 2010-10-22 or 2010-10-23
ge2010-10-22
Less than or equals match, which matches 2010-10-22 or 2010-10-21
le2010-10-22
address-postcode
String

The postcode of any of the patient’s known addresses. White spaces in postcodes are not significant; that is, LS16AE and LS1 6AE will both match LS1 6AE.

Must be URL encoded. For example a space must be represented by either %20 or +.

Examples
Spaces not important, would match LS16AE
LS1 6AE
Will match 'LS16AE', 'LS1 6AE' and 'LS1 6AB'
LS1*
general-practitioner
String
The Organisation Data Service (ODS) code of the patient's registered GP practice.
Example: Y00001

Response

HTTP status: 200

A completed search, containing zero, one, or many matching patients.

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/Patient/9000000009",
    "search" : {
      "score" : 1
    },
    "resource" : {
      "address" : [ {
        "extension" : [ {
          "extension" : [ {
            "url" : "type",
            "valueCoding" : {
              "code" : "PAF",
              "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-AddressKeyType"
            }
          }, {
            "url" : "value",
            "valueString" : "12345678"
          } ],
          "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-AddressKey"
        } ],
        "id" : "456",
        "line" : [ "1 Trevelyan Square", "Boar Lane", "City Centre", "Leeds", "West Yorkshire" ],
        "period" : {
          "end" : "2021-12-31",
          "start" : "2020-01-01"
        },
        "postalCode" : "LS1 6AE",
        "use" : "home"
      } ],
      "birthDate" : "2010-10-22",
      "contact" : [ {
        "id" : "C123",
        "period" : {
          "end" : "2021-12-31",
          "start" : "2020-01-01"
        },
        "relationship" : [ {
          "coding" : [ {
            "code" : "C",
            "display" : "Emergency Contact",
            "system" : "http://terminology.hl7.org/CodeSystem/v2-0131"
          } ]
        } ],
        "telecom" : [ {
          "system" : "phone",
          "value" : "01632960587"
        } ]
      } ],
      "deceasedDateTime" : "2010-10-22T00:00:00+00:00",
      "extension" : [ {
        "extension" : [ {
          "url" : "deathNotificationStatus",
          "valueCodeableConcept" : {
            "coding" : [ {
              "code" : "2",
              "display" : "Formal - death notice received from Registrar of Deaths",
              "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-DeathNotificationStatus",
              "version" : "1.0.0"
            } ]
          }
        }, {
          "url" : "systemEffectiveDate",
          "valueDateTime" : "2010-10-22T00:00:00+00:00"
        } ],
        "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-DeathNotificationStatus"
      } ],
      "gender" : "female",
      "generalPractitioner" : [ {
        "id" : "254406A3",
        "identifier" : {
          "period" : {
            "end" : "2021-12-31",
            "start" : "2020-01-01"
          },
          "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
          "value" : "Y12345"
        },
        "type" : "Organization"
      } ],
      "id" : "9000000009",
      "identifier" : [ {
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus",
          "valueCodeableConcept" : {
            "coding" : [ {
              "code" : "01",
              "display" : "Number present and verified",
              "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-NHSNumberVerificationStatus",
              "version" : "1.0.0"
            } ]
          }
        } ],
        "system" : "https://fhir.nhs.uk/Id/nhs-number",
        "value" : "9000000009"
      } ],
      "meta" : {
        "security" : [ {
          "code" : "U",
          "display" : "unrestricted",
          "system" : "https://www.hl7.org/fhir/valueset-security-labels.html"
        } ],
        "versionId" : "2"
      },
      "multipleBirthInteger" : 1,
      "name" : [ {
        "family" : "Smith",
        "given" : [ "Jane" ],
        "id" : "123",
        "period" : {
          "end" : "2021-12-31",
          "start" : "2020-01-01"
        },
        "prefix" : [ "Mrs" ],
        "suffix" : [ "MBE" ],
        "use" : "usual"
      } ],
      "resourceType" : "Patient",
      "telecom" : [ {
        "id" : "789",
        "period" : {
          "end" : "2021-12-31",
          "start" : "2020-01-01"
        },
        "system" : "phone",
        "use" : "home",
        "value" : "01632960587"
      }, {
        "extension" : [ {
          "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-OtherContactSystem",
          "valueCoding" : {
            "code" : "textphone",
            "display" : "Minicom (Textphone)",
            "system" : "https://fhir.nhs.uk/R4/CodeSystem/UKCore-OtherContactSystem"
          }
        } ],
        "id" : "OC789",
        "period" : {
          "end" : "2021-12-31",
          "start" : "2020-01-01"
        },
        "system" : "other",
        "use" : "home",
        "value" : "01632960587"
      } ]
    }
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object
resourceType
string
FHIR Resource Type.
type
string
FHIR Bundle Type.
timestamp
string datetime
Time the search was performed.
total
integer
Number of resources returned in search.
entry
array
A list of matched patients. Empty if none found. The patients are ordered by match score, best first. A maximum of 50 patients will be returned.
object
fullUrl
string
Absolute URL of the resource described in this item.
search
object
score
number
Search score from 0.0 to 1.0.
Maximum: 1 (inclusive)
Minimum: 0 (inclusive)
resource
object
resourceType
string
read-only
FHIR resource type.
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.
Pattern: ^\d{10}$
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.
value
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.
Pattern: ^\d{10}$
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.
valueCodeableConcept
object
NHS Number Verification Status Indicator.
coding
array
Max items: 1
Min items: 1
object
system
string
read-only
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
meta
object
Metadata about this resource.
versionId
string
read-only
The NHS Digital assigned version of the patient resource.
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 will be returned.
  • R - restricted. Any sensitive data around the patient's location, so address, generalPractitioner and telecom, will be removed from the response.
  • V - very restricted. All patient data will be removed from the response apart from id, identifier and meta fields. The gender field will return unknown regardless of actual gender.
  • REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code will never be returned; you will 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.
code
string
Code defined by the system value set.
display
string
Representation defined by the system.
name
array

List of names associated with the patient.

This will only be fully populated on a retrieval, only a the usual, nickname and temp names will be returned on a search.

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

Min items: 1
object
id
string
read-only
Unique object identifier for this name.
use
string

How this name should be used.

  • usual - Known as, conventional or the one patient normally uses. A patient will always have 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 will 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).
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
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
string
Max length: 35
family
string
Family name (often called Surname).
Max length: 35
prefix
array
Name prefixes, titles, and prenominals.
string
suffix
array
Name suffices and postnominals.
string
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.
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 will be removed from the response.
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)
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 will be 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]))$
address
array

List of addresses associated with the patient.

This will only be fully populated on a retrieval, only a the home address will be returned on a search.

When a patient tagged as restricted or very restricted is retrieved, all addresses will be removed from the response.
object
An address associated with the patient.
id
string
read-only
Unique system identifier for this address.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
use
string

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.
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 will not appear on the PDS, but the address used for it may.
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 will not be returned due to FHIR conformance constraints.

Max items: 5
string
postalCode
string
Postal code of the address.
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.
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
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 will be 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.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
system
string
Means of communication, such as phone or email.
value
string
Phone number, email address, or other identifier for use with contact system.
use
string
Location associated with communication system.
extension
array

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

The system will only ever be 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.
valueCoding
object
URL of specification of other contact systems.
system
string
read-only
URL of Code System that describes available contact relationships.
code
string
Coded value for the other contact system in place.
display
string
Display-friendly representation of the other contact system code.
contact
array

A list of patient contacts. Only emergency contacts will be returned. Any other contacts will be returned on the patients Related Person.

When a patient tagged as restricted or very restricted is retrieved, all contacts will be removed from the response.
object
Schema for a patient contact.
id
string
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
relationship
array

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

This will only return 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
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.
code
string
Coded value for contact relationship.
display
string
Display-friendly representation of the contact relationship code.
telecom
array
List of Telecom objects on the contact will only contain 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.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
system
string
Means of communication, such as phone or email.
value
string
Phone number, email address, or other identifier for use with contact system.
use
string
Location associated with communication system.
extension
array

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

The system will only ever be 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.
valueCoding
object
URL of specification of other contact systems.
system
string
read-only
URL of Code System that describes available contact relationships.
code
string
Coded value for the other contact system in place.
display
string
Display-friendly representation of the other contact system code.
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 will be 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.
type
string
read-only
Type of Reference being returned.
identifier
object
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.
value
string
Organisation code for the registered general practice, as held in the Organisation Data Service.
Pattern: ^[0-9A-Z]+$
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
extension
array
Wrapper array for the patient's death notification status; this is a FHIR extension. Always contains zero or one death notification status object.

HTTP status: 400

Invalid search paramaters supplied.

Body

Content type: application/fhir+json
Examples
too few search params
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "value",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "INVALID_SEARCH_DATA",
        "display" : "Search data is invalid"
      } ]
    },
    "diagnostics" : "Invalid search data provided - Not enough search parameters were provided to be able to make a search"
  } ]
}
Invalid combination of search parameters
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "value",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "INVALID_SEARCH_DATA",
        "display" : "Search data is invalid"
      } ]
    },
    "diagnostics" : "Invalid search data provided - 'Invalid Date Combination'"
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

Update patient details

patch

/Patient/{id}
Try this API

Overview

Use this endpoint to update patient details in PDS.

This is a 'patch' operation - you can update specific parts of the patient record, such as name or gender, without having to update the entire record.

The update process is asynchronous - if the request is accepted, a 202 response is returned with a polling URL in the Content-Location header. Poll this URL for the outcome of the update. See the polling endpoint /_poll/{message id} for more details.

The behaviour of this endpoint depends on which access mode you are using:

Access mode Behaviour restrictions
Healthcare professional access Full behaviour available
Application-restricted access Limited to a single unique result
Citizen access Not yet available

Patient resource versioning

To update a patient's resource you must have retrieved it first, to ensure you are working against an up-to-date patient resource.

When you retrieve a patient resource, you get a version number for the resource (in the ETag response header in the form W/"2" and in the versionId field in the response, in the form "2").

You must then pass the patient's version number in the update request (in the If-Match response header).

It is recommended you use the value from the Etag header as this is in the correct form the If-Match header is expected, for example W/"2" and can be mirrored back in the request.

The update will only succeed if the patient resource has not been updated in our database in the meantime.

If the update succeeds, on polling the outcome, you will receive a copy of the update resource in the response, including the new resource version number.

If you make a subsequent update you must use the new version number.

JSON Patch

To update a patient a JSON Patch should be sent. A JSON Patch consists of one or more patch objects within a list.

It is recommended that all desired updates are sent together in a single request as a list of patches. This is the most efficient approach and will reduce the danger of race conditions occurring when updating the patient multiple times in a short period of time.

When processing the list of patch objects, each patch must be valid and pass all the business rules against the data. If one patch object fails, none of the patch objects will be applied.

A patch object consists of:

  • an operation, op - this is required.
  • a path to the data that you want to change, path - this is required.
  • the value that will be assigned, value - this is required for add, replace and test; but should not be included for a remove.

The following operations are supported:

  • add - to add a new value.
  • replace - to replace an existing value.
  • remove - to remove an existing value.
  • test - to test the state of a value is as expected before continuing with the update.

Paths point to a single value, list or object, for example:

  • /gender - pointing to the gender value.
  • /name - point to the name list.
  • /name/0 - pointing to the 1st object in the name list.
  • /address/0/line/1 - pointing to the 2nd line string in the 1st address object.

The value can be set to any valid value for that path, so could be a null, a string, an object or a list.

Addition

add should be used to add new items to a patient.

Adding a simple data item such as the date of death can be done using a patch such as:

{
    "patches": [
      { "op": "add", "path": "/deceasedDate", "value": "2020-01-01" }
  ]
}

Adding to a list such as a name should be done by including the whole object in the value field. Note, the list index is - this is because when adding to a list as the index will not be known:

{
    "patches": [
      {
            "op": "add",
            "path": "/name/-",
            "value": {
                "use": "usual",
                "period": { "start": "2019-12-31" },
                "prefix": ["Dr"],
                "given": [
                  "Joe",
                  "Horation",
                  "Maximus"
                ],
                "family": "Bloggs",
                "suffix": ["PhD"]
            }
        }
  ]
}

When adding a base level list item such as a new name or address, ensure the index is always -, otherwise the request will be rejected. For example, /name/-. The reason for this is because the backend system will make the decision on the ordering of the listed objects to ensure they are always returned in the same order.

If you are adding to a sub-element that is a list, such as an additional given name, it is valid to provide an exact index. So the following is valid:

{
  "patches": [
    {
      "op": "add", "path": "/name/0/id", "value": "8F8B957D"
    },
    {
      "op": "add", "path": "/name/0/given/0", "value": "Rose"
    }
  ]
}

It is possible to add a sub-element to an existing object in a patch request. If the object already exists and you have the object id, you must supply it or the update will be rejected. The following patch is allowed:

{
  "patches": [
    {
      "op": "add", "path": "/name/0/id", "value": "8F8B957D"
    },
    {
      "op": "add", "path": "/name/0/given/0", "value": "Rose"
    }
  ]
}

but the following is not allowed:

{
  "patches": [
    {
      "op": "add", "path": "/name/0/given/-", "value": "Rose"
    }
  ]
}

Replacing

replace should be used to alter existing items on the patient.

Replacing a simple data item such as the gender can be done using a patch such as:

{
    "patches": [
      { "op": "replace", "path": "/gender", "value": "male" }
  ]
}

Replacing a list item can be done in two ways which may be dependent on any external development libraries that can be used to create the patch.

The first approach is to replace the whole list item:

{
    "patches": [
      {
            "op": "replace",
            "path": "/name/0",
            "value": {
                "id": "123",
                "use": "usual",
                "period": { "start": "2019-12-31" },
                "prefix": ["Dr"],
                "given": [
                  "Joe",
                  "Horation",
                  "Maximus"
                ],
                "family": "Bloggs",
                "suffix": ["PhD"]
            }
        }
  ]
}

The second approach is to replace just a part, or parts, of the list object keys if all others will remain the same:

{
    "patches": [
      { "op": "replace", "path": "/name/0/id", "value": "123" },
      { "op": "replace", "path": "/name/0/prefix/0", "value": "Mr" },
      { "op": "replace", "path": "/name/0/family", "value": "Smith" }
    ]
}

An added requirement to ensure no accidental data loss or replacement of the wrong list item, you must always include the list id or url. This will be in the object on retrieval so just needs to be mirrored back. You should not include an ID on an addition as this will be automatically generated by the system and is a unique object ID, so only our system can guarantee that.

Removal

remove should be used to delete existing items on a patient.

Removing a simple data item such as the gender can be done using a patch such as:

{
    "patches": [
      { "op": "remove", "path": "/gender" }
  ]
}

Note, that in this scenario, although the patch is perfectly valid, the update will still be rejected as a patients gender cannot be removed.

Removing a list item should only be done on the whole item object, not individual sub-items; instead use the replace operation.

To remove a list item, a test operation must immediately proceed the remove . This is an added requirement to ensure no accidental data loss occurs or the wrong item is removed. The test operation should be used to assert either:

  • the id - the object ID for items that have one - for example name, address or telecom.
  • the url - the URL for the extension being removed.
  • the whole object being removed.

An example of a list item removal using the id would be:

{
    "patches": [
      { "op": "test", "path": "/name/0/id", "value": "123" },
      { "op": "remove", "path": "/name/0" }
  ]
}

An example of a extension list item removal using the url would be:

{
    "patches": [
      { "op": "test", "path": "/extension/0/url", "value": "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-DeathNotificationStatus" },
      { "op": "remove", "path": "/extension/0" }
  ]
}

An example of a list item removal using the whole object would be:

{
    "patches": [
      { 
            "op": "test",
            "path": "/name/0",
            "value": {
                "id": "123",
                "use": "usual",
                "period": { "start": "2019-12-31" },
                "prefix": ["Dr"],
                "given": [
                  "Joe",
                  "Horation",
                  "Maximus"
                ],
                "family": "Bloggs",
                "suffix": ["PhD"]
            }
        },
      { "op": "remove", "path": "/name/0" }
  ]
}

Special care should be taken when performing multiple removals in the same list; as removing a particular index could affect all subsequent index positions. The next two examples perform exactly the same operation.

Using the following initial (simplified) data, with the intention of removing the names in index 1 (Irwin) and 2 (Bruce):

{
    "name": [
        {"id": "2", "family": "Parker"},
        {"id": "3", "family": "Irwin"},
        {"id": "4", "family": "Bruce"},
        {"id": "5", "family": "Sharpe"}
    ]
}

Example 1:

{
    "patches": [
      { "op": "test", "path": "/name/1/id", "value": "3" },
      { "op": "remove", "path": "/name/1" },
      { "op": "test", "path": "/name/1/id", "value": "4" },
      { "op": "remove", "path": "/name/1" }
  ]
}

After the 1st removal the data will look like:

{
    "name": [
        {"id": "2", "family": "Parker"},
        {"id": "4", "family": "Bruce"},
        {"id": "5", "family": "Sharpe"}
    ]
}

meaning Irwin has been removed, Bruce has moved from index 2 -> 1 and Sharpe from 3 -> 2.

So after applying the 2nd removal the data will look like:

{
    "name": [
        {"id": "2", "family": "Parker"},
        {"id": "5", "family": "Sharpe"}
    ]
}

Which is the intended outcome. Using the same index 1 for both removals may look unexpected, but the way JSON Patch works is iterating over each patch operation in turn and making the change to the list index positions. This means a developer needs to account for lists changing from one operation to the next.

Example 2:

{
    "patches": [
      { "op": "test", "path": "/name/2/id", "value": "4" },
      { "op": "remove", "path": "/name/2" },
      { "op": "test", "path": "/name/1/id", "value": "3" },
      { "op": "remove", "path": "/name/1" }
  ]
}

After the 1st removal the data will look like:

{
    "name": [
        {"id": "2", "family": "Parker"},
        {"id": "3", "family": "Irwin"},
        {"id": "5", "family": "Sharpe"}
    ]
}

Applying the 2nd removal the data will look like:

{
    "name": [
        {"id": "2", "family": "Parker"},
        {"id": "5", "family": "Sharpe"}
    ]
}

Which is the intended outcome. Providing the patches with the indexes descending means that the list stays in a stable format the whole way through as the only changes to the index positions are items have been passed over already.

Example 3 - a failure

{
    "patches": [
      { "op": "test", "path": "/name/1/id", "value": "3" },
      { "op": "remove", "path": "/name/1" },
      { "op": "test", "path": "/name/2/id", "value": "4" },
      { "op": "remove", "path": "/name/2" }
  ]
}

After the 1st removal the data will look like:

{
    "name": [
        {"id": "2", "family": "Parker"},
        {"id": "4", "family": "Bruce"},
        {"id": "5", "family": "Sharpe"}
    ]
}

When applying the 2nd test, it will fail as the index 2 ID is 5, but the test was looking for 4. An error will be returned and none of the updates provided would be made to the database.

This failure example is a good reason for forcing the use of the test operation. If there was no test, index 2 would have been blindly removed, meaning the final state of the data would look like:

{
    "name": [
        {"id": "2", "family": "Parker"},
        {"id": "4", "family": "Bruce"}
    ]
}

Which is incorrect, as Irwin and Sharpe were removed instead of Irwin and Bruce.

Patient data fields

Address

List item found under address field.

In a JSON Patch request the path should be:

  • /address/0 if the address to be replaced or removed is the first item in the list. If it is the second item in the list the path will be /address/1, and so on.
  • /address/- when adding a new address.

An address consists of 5 lines of unstructured text, postcode and PAF (Postcode Address File) key. Local 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

When updating an address, lines 1 or 2, and line 4 should be populated; line 5 should not be included in manually created addresses but may be included in PAF derived addresses.

Address lines should be populated otherwise the message may be rejected. There are exceptions:

  • if a postcode and PAF key are submitted, in which case the lines will be automatically populated, however if there are no matches or too many matches the message will be rejected due to missing address lines
  • a pseudo postcode is used. For example ZZ99 3VZ meaning no fixed abode

When creating the FHIR payload message, to be fully FHIR compliant all empty lines should be removed, so for example:

{
    "address": {
        "line": [
            "",
            "23 Mill Lane",
            "",
            "Leeds",
            ""
        ]
    }

}

should be sent in as:

        {
            "address": {
                "line": [
                    "23 Mill Lane",
                    "Leeds"
                ]
            }

        }

however if you do not do this the message will not be rejected; the response will be in that form though.

To ensure consistent data across all patient addresses it is advised that the address data supplied should be matched to the PAF and sent in that format including the PAF key. If the PAF key is not included it will be added to the address if a match can be found, additionally the provided address lines and post code will be enriched and reformatted if necessary.

The following address types are supported:

  • 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

A patient should have no more than one current temp and/or billing address, attempting to add multiple will result in a error. 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 to 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 to dates.
  • if there is no valid, current billing and/or temp address, the home address must be used.

It should be noted that not all local systems support temp and billing addresses, so these are not uniformly maintained. Therefore, where the patient contact has clinical or business significance, the precedence of these addresses over the home address should be determined by a user wherever possible. When the end date for a temp or billing address passes, local systems should use the patient’s home address. It will be extremely rare that no home address is present on a patient record.

There are a number of business rules that should be taken into account:

  • cannot add more than one of each address use types; home, temp or billing
  • work address use type is a valid response but cannot be added or replaced as it is a legacy value. An address with the work type can be removed though
  • any temp address must have both a period start and a period end date. The provision of a period end date has particular importance in order to avoid temporary addresses that are no longer relevant to the patient still being held as current data available to any system retrieving the patient record. A suggested default where no actual period end is known is 30 days later than the period start, up to a maximum of 3 months.
  • any billing address must have both a period start and a period end date. The provision of a period end date has particular importance in order to avoid correspondence addresses that are no longer relevant to the patient still being held as current data available to any system retrieving the patient record. A suggested default where no actual period end is known is 30 days later than the period start, up to a maximum of 12 months.
  • the date period is optional; where present they must be valid dates and the end date cannot be before the start date
  • the period start date is optional, however if provided cannot be a future date. If it is not provided it will default to the date of update
  • where a temp address is provided a description must be sent using the text field, 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

Valid pseudo postcodes are:

Postcode Description
ZZ99 3VZ No Fixed Abode
ZZ99 3WZ Address Not Known
ZZ99 3CZ England UK - not specified
ZZ99 3GZ Wales
ZZ99 1WZ Scotland
ZZ99 2WZ Northern Ireland
ZZ99 4MZ Austria
ZZ99 2DZ Belgium
ZZ99 4UZ Bulgaria
ZZ99 5VZ Croatia
ZZ99 6AZ Cyprus (Southern)
ZZ99 5XZ Czech Republic
ZZ99 4FZ Denmark
ZZ99 7LZ Estonia
ZZ99 4BZ Finland
ZZ99 4GZ France
ZZ99 4QZ Germany
ZZ99 4RZ Greece
ZZ99 4XZ Hungary
ZZ99 4CZ Iceland
ZZ99 4LZ Italy
ZZ99 7RZ Latvia
ZZ99 2PZ Liechtenstein
ZZ99 7SZ Lithuania
ZZ99 2EZ Luxembourg
ZZ99 5BZ Malta
ZZ99 4EZ Netherlands
ZZ99 2AZ Norway
ZZ99 4YZ Poland
ZZ99 4JZ Portugal
ZZ99 3AZ Republic of Ireland
ZZ99 4ZZ Romania
ZZ99 5YZ Slovakia
ZZ99 5UZ Slovenia
ZZ99 4HZ Spain
ZZ99 2CZ Sweden
ZZ99 4PZ Switzerland

Communication

Single item found under extension with the extension URL https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-NHSCommunication.

In a JSON Patch request, where the communication extension doesn't exist the path should be:

  • /extension/- when adding a communication extension.

Where you are replacing/removing the full communication extension, the path should be:

  • /extension/0 if the communication extension is the first item in the list. If it is the second item in the list the path will be /extension/1, and so on.

Where the communication extension already exists and you wish to replace a specific sub-extension, then the path should be:

  • /extension/0/extension/1 if the communication extension is the first item in the list and the sub-extension is the second item in the list.

You can find examples of the above requests in our sandbox Postman collection

There are a number of business rules that should be taken into account:

  • preferred language must not be supplied where it is English even though the code list contains a value for English (en).
  • any language codes outside the accepted list will be rejected; such as local system qa codes.

Contact preferences

Single item found under extension with the extension URL https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactPreference.

In a JSON Patch request, where the Contact Preference extension doesn't exist or you are replacing/removing the full list of Contact preferences, the path should be:

  • /extension/0 if the contact preference is the first item in the list. If it is the second item in the list the path will be /extension/1, and so on.
  • /extension/- when adding a contact preference.

Where the Contact Preference extension already exists and you wish to add, replace or remove a specific contact preference(s) sub-extension, then the path should be:

  • /extension/0/extension/1 if the contact preference extension is the first item in the list and the method is the second item in the sub-extension list.

You can find examples of the above requests in our sandbox Postman collection

There are a number of business rules that should be taken into account:

  • a patient can have 0 or 1 contact preference.
  • preferred contact time is a free-text field limited to 40 characters.
  • where a contact time is specified a contact method must also exist.

Date of birth

Single item found under birthDate field.

In a JSON Patch request the path should be /birthDate.

When adding or updating the birth date, the update should be in the format yyyy-mm-dd.

There are a number of business rules that should be taken into account:

  • cannot be removed.
  • cannot be a date in the future.
  • cannot be after the deceased date, if present.

Date of death

Single item found under deceasedDateTime field.

In a JSON Patch request the path should be /deceasedDateTime.

When adding or updating the deceased date time, the update should be in the format yyyy-mm-ddTHH:MM:SS+HH:MM.

There are a number of business rules that should be taken into account:

  • cannot be removed.
  • cannot be a date in the future.
  • cannot be before the birth date.
  • cannot be replaced if the death notification status is 2 (formal).
  • when adding date of death, a death notification status must also be added.

Death notification

Single item found under extension with the extension URL https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-DeathNotificationStatus.

In a JSON Patch request the path should be:

  • /extension/0 if the death notification is the first item in the list. If it is the second item in the list the path will be /extension/1, and so on.
  • /extension/- when adding a death notification.

You can find examples of the above requests in our sandbox Postman collection

There are a number of business rules that should be taken into account:

  • cannot be removed.
  • cannot be replaced if the death notification status is formal (2).
  • only certain endpoints can set a death notification of formal (2).
  • when adding a death notification, a deceased date time must also be added.

Emergency contact

List item found under contact field.

In a JSON Patch request the path should be:

  • /contact/0 if the contact to be replaced or removed is the first item in the list. If it is the second item in the list the path will be /contact/1, and so on.
  • /contact/- when adding a new contact.

Only emergency contact details should be added to contact, regular telecommunication methods such as home phone should be added to the telecom field. Any other contact relationship types will be rejected.

There are a number of business rules that should be taken into account:

  • in any telecom child object the use key should not be present.
  • in any telecom child object the system cannot be fax.
  • the date period is optional; where present they must be valid dates and the end date cannot be before the start date.
  • the period start date is optional, however if provided cannot be a future date. If it is not provided it will default to the date of update.
  • the date period, if present, should be on the parent contact object and not any telecom child objects.
  • if the telecom system is email, the value must be a valid email format, for example john.smith@nhs.net; be more than 6 characters and less than 90 characters
  • the relationship can only be C meaning Emergency Contact

Gender

Single item found under gender field.

In a JSON Patch request the path should be /gender.

When setting a gender, the local system should encourage the user to select male or female rather than unknown. The fourth value of gender, other, meaning indeterminate; i.e. unable to be classified as either male or female; should never pro-actively be set by local systems - although this value can be retrieved due to legacy data or data quality issues.

There are a number of business rules that should be taken into account:

  • cannot be removed.
  • can only be male, female or unknown.
  • cannot set gender to other.

General practice

List item found under generalPractitioner field. Although only a single general practice is allowed.

In a JSON Patch request the path should be:

  • /generalPractitioner/0 for replacing or removing the general practice.
  • /generalPractitioner/- when adding a new general practice.

There are a number of business rules that should be taken into account:

  • only valid GP Practice codes may be used, see Organisation Data Service FHIR API for more details on valid codes.
  • the period start date is optional, however if provided cannot be a future date. If it is not provided it will default to the date of update.
  • do not provide a period end date.
  • the general practice should only be updated by primary care systems, NHAIS or by the National Back Office.
  • removal of a general practice can only be done by NHAIS or by the National Back Office.
  • only a single general practice is supported; emergency, temporary and additional practices must be maintained in the local system only.

Multiple birth order

Single item found under multipleBirthInteger field.

In a JSON Patch request the path should be /multipleBirthInteger.

When adding or updating the birth order, the update should be an integer in the range 1 - 9 inclusive. These values have differing meanings:

  • 1 - 7 indicates the order of birth, 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.
  • 8 - Not applicable
  • 9 - Not known

Name

List item found under name field.

In a JSON Patch request the path should be:

  • /name/0 if the name to be replaced or removed is the first item in the list. If it is the second item in the list the path will be /name/1, and so on.
  • /name/- when adding a new name.

There are a number of business rules that should be taken into account:

  • cannot add more than one usual name.
  • cannot remove the usual name.
  • cannot add more than one nickname.
  • can have multiple instances of all other name use types.
  • cannot replace the use type on an existing name. For example, once a name is a nickname, it cannot be changed directly to an alias. You must instead remove the nickname and add the alias.
  • the first character of each suffix item must be A-Z.
  • the date period is optional; where present they must be valid dates and the end date cannot be before the start date.
  • the period start date is optional, however if provided cannot be a future date. If it is not provided it will default to the date of update.
  • supplied name data must be UTF-8 encodable.
  • the period is optional, but if included the end date cannot be before the start date. They can however be in the past, present or future.
  • the full available range of generally recognised titles are permitted, however, if any of the following are used then the value input must conform to the following format:
    • Mr
    • Mrs
    • Ms
    • Dr
    • Rev
    • Sir
    • Lady
    • Lord
  • any trailing full stops at the end of a prefix will be automatically removed; for example Mrs. will be changed to Mrs.

Pharmacy

Single item found under extension with one of the extension urls:

  • https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-NominatedPharmacy
  • https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier
  • https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization

In a JSON Patch request the path should be:

  • /extension/0 if the pharmacy is the first item in the list. If it is the second item in the list the path will be /extension/1, and so on
  • /extension/- when adding a pharmacy

There are a number of business rules that should be taken into account:

  • multiple pharmacies are allowed, however only one of each type
  • there are no effective date periods, only a single current instance of each type is supported
  • only valid National Pharmacy codes may be used for the pharmacy identifier, see Organisation Data Service FHIR API for more details on valid codes

Place of birth

Single item found under extension with the extension URL http://hl7.org/fhir/StructureDefinition/patient-birthPlace.

In a JSON Patch request the path should be:

  • /extension/0 if the place of birth is the first item in the list. If it is the second item in the list the path will be /extension/1, and so on
  • /extension/- when adding a place of birth

There are a number of business rules that should be taken into account:

  • the three fields, city, district and country are all optional, however at least one of them must be provided
  • country is a coded value and must be in the set of valid values

Telecom

List item found under telecom field.

In a JSON Patch request the path should be:

  • /telecom/0 if the telecom to be replaced or removed is the first item in the list. If it is the second item in the list the path will be /telecom/1, and so on
  • /telecom/- when adding a new telecom

Emergency contact details should not be added to the telecom field, instead they should be added to the contact field.

There are a number of business rules that should be taken into account:

  • the date period is optional; where present they must be valid dates and the end date cannot be before the start date
  • the period start date is optional, however if provided cannot be a future date. If it is not provided it will default to the date of update.
  • if the system is email, the value must be a valid email format, for example john.smith@nhs.net; be more than 6 characters and less that 90 characters

Sandbox test scenarios

You can test the following scenarios in our sandbox environment.

Things to note when using the sandbox for PATCH:

  • Your changes will not be persisted.
  • JSON Patch operations themselves are validated, but the resulting resource is not validated for correctness; meaning any business rules are not applied.
  • You can use the patient with minimal data, 9000000033 to test adding all data types (as most of them are missing on this patient), that would normally be present (e.g. gender).
Scenario Request Response
Successful update id=9000000009

Body: One of the provided examples or your own combination of patches

Headers: If-Match=W/"2", Content-Type=application/json-patch+json		 HTTP Status 202 with the message URL to poll in the Content-Location header
Patient doesn't exist id=9111231130 (or any other valid NHS Number) HTTP Status 404 with problem description
Invalid NHS Number id=9000000000 (or any invalid NHS Number) HTTP Status 400 with problem description
Missing resource version identifier If-Match header missing or set to format other than W/"<version>" HTTP Status 412 with problem description
Incorrect resource version If-Match=W/"1" HTTP Status 412 with problem description
Wrong content type Content-Type header missing or other than application/json-patch+json HTTP Status 400 with problem description
No patches sent Send body with no patches attribute HTTP Status 400 with problem description
Invalid patch operations Send body with invalid JSON patches in patches attribute 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

Download Postman client

If you don’t have it, you can download Postman here.

Click on the download button in the top right corner and follow the instructions.

Download our collection

If you already have the Postman client installed - click onto our postman collection (button above) - then click onto the ‘Postman for Windows’ or ‘Postman for Mac’ version - and click Open when prompted.

Postman client should then open showing our Patient Demographics Sandbox.

If you have already downloaded the Sandbox collection from one of our other endpoints, found under the PDS FHIR API pages, you don't have to download it again as the same collection covers all endpoints.


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
If-Match
String

Latest known version identifier enclosed in quotes preceded by W/.

Send the value of the patient's ETag response header on patient retrieval when updating a patient. This is to ensure that any updates are applied against an up-to-date version of the patient resource.

Pattern: /^W\/"[0-9]+"$/
Example: W/"2"
Required
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. Also optional in sandbox.

Pattern: /^[0-9]+$/
Example: 555021935107
Authorization
String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
X-Correlation-ID
String

A globally unique identifier (GUID) for the request, which we use to trace the request if you contact our helpdesk.

Mirrored back in a response header.

Avoid . characters.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Request-ID
String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests.

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

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

Mirrored back in a response 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

Body

Required
Content type: application/json
Examples
Add a new single item (deceasedDateTime) to the patient
{
  "patches" : [ {
    "op" : "add",
    "path" : "/deceasedDateTime",
    "value" : "2010-10-22T00:00:00+00:00"
  } ]
}
Add a new list item (name) to the patient
{
  "patches" : [ {
    "op" : "add",
    "path" : "/name/-",
    "value" : {
      "use" : "usual",
      "period" : {
        "start" : "2019-12-31"
      },
      "prefix" : [ "Dr" ],
      "given" : [ "Joe", "Horation", "Maximus" ],
      "family" : "Bloggs",
      "suffix" : [ "PhD" ]
    }
  } ]
}
Add a an extension (nominated pharmacy) to the Patient
{
  "patches" : [ {
    "op" : "add",
    "path" : "/extension/-",
    "value" : {
      "url" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-NominatedPharmacy",
      "valueReference" : {
        "identifier" : {
          "system" : "https://fhir.nhs.uk/Id/ods-organization-code",
          "value" : "Y12345",
          "period" : {
            "start" : "2020-01-01",
            "end" : "2021-12-31"
          }
        }
      }
    }
  } ]
}
Update the simple item (gender)
{
  "patches" : [ {
    "op" : "replace",
    "path" : "/gender",
    "value" : "male"
  } ]
}
Update specific fields on a list item (address)
{
  "patches" : [ {
    "op" : "replace",
    "path" : "/address/0/line/0",
    "value" : "2 Whitehall Quay"
  }, {
    "op" : "replace",
    "path" : "/address/0/postalCode",
    "value" : "LS1 4BU"
  } ]
}
Update whole object on a list item (address)
{
  "patches" : [ {
    "op" : "replace",
    "path" : "/address/0",
    "value" : {
      "id" : "456",
      "period" : {
        "start" : "2020-01-01",
        "end" : "2021-12-31"
      },
      "use" : "home",
      "line" : [ "2 Whitehall Quay", "Leeds", "West Yorkshire" ],
      "postalCode" : "LS1 4BU",
      "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" : "9876543"
        } ]
      } ]
    }
  } ]
}
Update an extension (death notification)
{
  "patches" : [ {
    "op" : "replace",
    "path" : "/extension/3",
    "value" : {
      "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" : "1",
            "display" : "Informal - death notice received via an update from a local NHS Organisation such as GP or Trust"
          } ]
        }
      } ]
    }
  } ]
}
Remove a single item (gender) no longer in use
{
  "patches" : [ {
    "op" : "remove",
    "path" : "/gender"
  } ]
}
Remove a list item (name) no longer in use, using test pointing to the name items id
{
  "patches" : [ {
    "op" : "test",
    "path" : "/name/0/id",
    "value" : "123"
  }, {
    "op" : "remove",
    "path" : "/name/0"
  } ]
}
Remove a list item (name) no longer in use, using test pointing to the name object
{
  "patches" : [ {
    "op" : "test",
    "path" : "/name/0",
    "value" : {
      "id" : "123",
      "use" : "usual",
      "period" : {
        "start" : "2020-01-01",
        "end" : "2021-12-31"
      },
      "given" : [ "Jane" ],
      "family" : "Smith",
      "prefix" : [ "Mrs" ],
      "suffix" : [ "MBE" ]
    }
  }, {
    "op" : "remove",
    "path" : "/name/0"
  } ]
}
Remove an extension (dispensing doctor pharmacy) no longer in use
{
  "patches" : [ {
    "op" : "test",
    "path" : "/extension/1/url",
    "value" : "https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization"
  }, {
    "op" : "remove",
    "path" : "/extension/1"
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object
patches
array
object
op
string
path
string jsonpointer
The location of the information to remove, add or replace. The '-' character must be used to add new items to arrays, e.g. names, addresses.
value
The information to be added or replaced. Should not be included on a remove.

Response

HTTP status: 202

The patch was syntactically correct and was accepted.

A polling location will be returned in the Content-Location header and the polling interval in the Retry-After header.

Note, the patch may still fail after it is accepted, for example, further validation of the patch may still result in business rule failures. Therefore, it should not be assumed that the patient is successfully updated after receiving acceptance of the message.

See the polling endpoint for more details.

Headers

Name Description
Content-Location
String
Polling location of the update
Example: /_poll/20200522091633363041_461139_1524772598
Retry-After
String
Time to wait between polls in milliseconds
Example: 100

HTTP status: 400

Client error.

Body

Content type: application/fhir+json
Examples
Invalid NHS number supplied
{
  "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"
      } ]
    }
  } ]
}
No patches submitted
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "required",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "MISSING_VALUE",
        "display" : "Required value is missing"
      } ]
    },
    "diagnostics" : "Missing value - patches"
  } ]
}
Invalid patch operation(s)
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "value",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "INVALID_UPDATE",
        "display" : "Update is invalid"
      } ]
    },
    "diagnostics" : "Invalid update with error - Invalid payload received - incorrect format"
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

HTTP status: 412

Precondition failed.

The version identifier submitted in the If-Match header was not the latest version of the resource.

Body

Content type: application/fhir+json
Examples
Invalid If-Match header
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "structure",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "PRECONDITION_FAILED",
        "display" : "Required condition was not fulfilled"
      } ]
    },
    "diagnostics" : "Invalid update with error - This resource has changed since you last read. Please re-read and try again with the new version number"
  } ]
}
Missing If-Match header
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "required",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "PRECONDITION_FAILED",
        "display" : "Required condition was not fulfilled"
      } ]
    },
    "diagnostics" : "Invalid update with error - If-Match header must be supplied to update this resource"
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

Endpoint: Polling

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 will be returned with a Content-Location header, use this location to poll for the outcome. It will be 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 will provide the time to wait in milliseconds between polls, although polling with a larger gap is also allowed. Retrieval of the outcome will not occur any faster by polling more frequently. The server will simply return 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

Download Postman client

If you don’t have it, you can download Postman here.

Click on the download button in the top right corner and follow the instructions.

Download our collection

If you already have the Postman client installed - click onto our postman collection (button above) - then click onto the ‘Postman for Windows’ or ‘Postman for Mac’ version - and click Open when prompted.

Postman client should then open showing our Patient Demographics Sandbox.

If you have already downloaded the Sandbox collection from one of our other endpoints, found under the PDS FHIR API pages, you don't have to download it again as the same collection covers all endpoints.


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
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. Also optional in sandbox.

Pattern: /^[0-9]+$/
Example: 555021935107
Authorization
String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
X-Correlation-ID
String

A globally unique identifier (GUID) for the request, which we use to trace the request if you contact our helpdesk.

Mirrored back in a response header.

Avoid . characters.

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"

Body

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

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object
resourceType
string
read-only
FHIR resource type.
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.
Pattern: ^\d{10}$
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.
value
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.
Pattern: ^\d{10}$
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.
valueCodeableConcept
object
NHS Number Verification Status Indicator.
coding
array
Max items: 1
Min items: 1
object
system
string
read-only
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
meta
object
Metadata about this resource.
versionId
string
read-only
The NHS Digital assigned version of the patient resource.
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 will be returned.
  • R - restricted. Any sensitive data around the patient's location, so address, generalPractitioner and telecom, will be removed from the response.
  • V - very restricted. All patient data will be removed from the response apart from id, identifier and meta fields. The gender field will return unknown regardless of actual gender.
  • REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code will never be returned; you will 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.
code
string
Code defined by the system value set.
display
string
Representation defined by the system.
name
array

List of names associated with the patient.

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

Min items: 1
object
id
string
read-only
Unique object identifier for this name.
use
string

How this name should be used.

  • usual - Known as, conventional or the one patient normally uses. A patient will always have 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 will 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).
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
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
string
Max length: 35
family
string
Family name (often called Surname).
Max length: 35
prefix
array
Name prefixes, titles, and prenominals.
string
suffix
array
Name suffices and postnominals.
string
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.
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 will be removed from the response.
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)
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 will be 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]))$
address
array

List of addresses associated with the patient.

This will only be fully populated on a retrieval, only a the home address will be returned on a search.

When a patient tagged as restricted or very restricted is retrieved, all addresses will be removed from the response.
object
An address associated with the patient.
id
string
read-only
Unique system identifier for this address.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
use
string

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.
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 will not appear on the PDS, but the address used for it may.
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 will not be returned due to FHIR conformance constraints.

Max items: 5
string
postalCode
string
Postal code of the address.
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.
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
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 will be 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.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
system
string
Means of communication, such as phone or email.
value
string
Phone number, email address, or other identifier for use with contact system.
use
string
Location associated with communication system.
extension
array

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

The system will only ever be 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.
valueCoding
object
URL of specification of other contact systems.
system
string
read-only
URL of Code System that describes available contact relationships.
code
string
Coded value for the other contact system in place.
display
string
Display-friendly representation of the other contact system code.
contact
array

A list of patient contacts. Only emergency contacts will be 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 will be removed from the response.
object
Schema for a patient contact.
id
string
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
relationship
array

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

This will only return 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
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.
code
string
Coded value for contact relationship.
display
string
Display-friendly representation of the contact relationship code.
telecom
array
List of Telecom objects on the contact will only contain 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.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
system
string
Means of communication, such as phone or email.
value
string
Phone number, email address, or other identifier for use with contact system.
use
string
Location associated with communication system.
extension
array

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

The system will only ever be 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.
valueCoding
object
URL of specification of other contact systems.
system
string
read-only
URL of Code System that describes available contact relationships.
code
string
Coded value for the other contact system in place.
display
string
Display-friendly representation of the other contact system code.
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 will be 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.
type
string
read-only
Type of Reference being returned.
identifier
object
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.
value
string
Organisation code for the registered general practice, as held in the Organisation Data Service.
Pattern: ^[0-9A-Z]+$
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
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 will be removed from the response.

HTTP status: 400

Client error after the patch was accepted and patient was not updated.

Body

Content type: application/fhir+json
Example
Business rule failure; start date was after the end date.
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "structure",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "INVALID_UPDATE",
        "display" : "Update is invalid"
      } ]
    },
    "diagnostics" : "Invalid update with error - business effective start date is after the end date"
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

HTTP status: 403

Part of your update could not be allowed as the change was forbidden.

Body

Content type: application/fhir+json
Example
Date of death cannot be removed once it has been set.
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "information",
    "code" : "forbidden",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "FORBIDDEN_UPDATE",
        "display" : "Update is forbidden"
      } ]
    },
    "diagnostics" : "Forbidden update with error - source not permitted to remove 'deceasedDateTime'"
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

HTTP status: 404

The message ID not found or you did not have permission to poll for that message.

Body

Content type: application/fhir+json
Example
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "information",
    "code" : "not-found",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "POLLING_ID_NOT_FOUND",
        "display" : "The polling ID was not found"
      } ]
    }
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

HTTP status: 409

Version Conflict.

The version identifier submitted in the If-Match header was not the latest version of the resource.

Body

Content type: application/fhir+json
Example
Version mis-match
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "conflict",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "RESOURCE_VERSION_MISMATCH",
        "display" : "Resource version supplied does not match actual version"
      } ]
    }
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

HTTP status: 422

The polling message ID was found however the processing of the request failed in an unexpected way or was cancelled, so the update failed.

Please raise these occurrences with our team (via https://digital.nhs.uk/developer/help-and-support) so we can investigate the issue. When raising, quote the message ID you were polling for.

Body

Content type: application/fhir+json
Example
{
  "resourceType" : "OperationOutcome",
  "issue" : [ {
    "severity" : "error",
    "code" : "processing",
    "details" : {
      "coding" : [ {
        "system" : "https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode",
        "version" : "1",
        "code" : "POLLING_MESSAGE_FAILURE",
        "display" : "The polling ID was found however the processing of the request failed in an unexpected way or was cancelled"
      } ]
    }
  } ]
}
Schema

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object

Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, 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.

There are general outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | ACCESS_DENIED | 401 | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. | | FAILURE_TO_PROCESS_MESSAGE | 500 | A default message when something really bad has happened that the system could not handle. | | UNABLE_TO_CALL_SERVICE | 408 | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. | | UNSUPPORTED_SERVICE | 400 | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets | | RESOURCE_NOT_FOUND | 404 | The resource was not found. | | INVALID_RESOURCE_ID | 400 | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. | | INVALIDATED_RESOURCE | 404 | The resource has been invalidated so could not be returned. |

Search outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | INVALID_SEARCH_DATA | 400 | The search parameters are invalid. A description of what exactly is at fault will be added to the display. | | TOO_MANY_MATCHES | 200 | Too many matches were found - user should be told to refine their search parameters. |

Update outcomes: | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | PRECONDITION_FAILED | 412 | Request missing basic requirements such as If-Match header (or invalid headers). | | RESOURCE_VERSION_MISMATCH | 409 | The resource version has changed since your last read, so the update has been rejected. | | FORBIDDEN_UPDATE | 403 | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. | | VALIDATION_ERROR | 400 | This it the "default" error thrown when no others are applicable. | | INVALID_UPDATE | 400 | The update was invalid - a detailed description will be added to the display. | | MISSING_VALUE | 400 | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display. | | INVALID_VALUE | 400 | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. | | UNSUPPORTED_VALUE | 400 | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. | | TOO_FEW_VALUES_SUBMITTED | 400 | The field in question has a minimum number of items and the user sent too few. | | TOO_MANY_VALUES_SUBMITTED | 400 | The field in question has a maximum number of items and the user sent too many. | | ADDITIONAL_PROPERTIES | 400 | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |

Polling outcomes | Code | Response Code | Description | | -------------------------- | ------------- | --------------------------------------------- | | POLLING_ID_NOT_FOUND | 404 | When polling the ID was not found - or it was not applicable such as a non polling ID. | | POLLING_MESSAGE_FAILURE | 422 | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
resourceType
string
read-only
FHIR Resource Type.
issue
array
List of issues that have occurred.
Min items: 1
object
severity
string
Severity of the error.
code
string
FHIR error code.
details
object
Internal error code.
coding
array
object
read-only
system
string
URI of the coding system specification.
version
string
Version of the coding system in use.
code
string
Symbol in syntax defined by the system.
display
string
Representation defined by the system.
diagnostics
string
Additional diagnostic information about the issue.
expression
string
FHIRPath of element(s) related to the error.

Endpoint: Relatedperson

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 will not be returned for a restricted patient and an empty bundle will be 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 will be 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

Download Postman client

If you don’t have it, you can download Postman here.

Click on the download button in the top right corner and follow the instructions.

Download our collection

If you already have the Postman client installed - click onto our postman collection (button above) - then click onto the ‘Postman for Windows’ or ‘Postman for Mac’ version - and click Open when prompted.

Postman client should then open showing our Patient Demographics Sandbox.

If you have already downloaded the Sandbox collection from one of our other endpoints, found under the PDS FHIR API pages, you don't have to download it again as the same collection covers all endpoints.


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
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. Also optional in sandbox.

Pattern: /^[0-9]+$/
Example: 555021935107
Authorization
String (^Bearer\ [[:ascii:]]+$)

An OAuth 2.0 bearer token.

Required in all environments except sandbox.

Example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
X-Correlation-ID
String

A globally unique identifier (GUID) for the request, which we use to trace the request if you contact our helpdesk.

Mirrored back in a response header.

Avoid . characters.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
X-Request-ID
String

A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests.

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

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

Mirrored back in a response 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

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"

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

To see the schema, open Try this API and select the 'Schema' tab.

Name Description
object
resourceType
string
FHIR Resource Type.
type
string
FHIR Bundle Type.
timestamp
string datetime
Time the search was performed.
total
integer
Number of resources returned in search.
entry
array
A list of related people details attached to the patient.
object
fullUrl
string
Absolute URL of the resource described in this item.
resource
object
id
string
read-only
Unique object identifier for this name.
resourceType
string
read-only
FHIR resource type.
patient
object
type
string
read-only
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.
value
string
NHS Number for the related person
Pattern: ^\d{10}$
reference
string url
read-only
URL for the FHIR Patient resource.
active
boolean
read-only
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
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.
use
string

How this name should be used.

  • usual - Known as, conventional or the one patient normally uses. A patient will always have 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 will 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).
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
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
string
Max length: 35
family
string
Family name (often called Surname).
Max length: 35
prefix
array
Name prefixes, titles, and prenominals.
string
suffix
array
Name suffices and postnominals.
string
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.
period
object
Business effective period when name was, is, or will be in use.
start
string date
Start date of time period, if known, in format yyyy-mm-dd. Can be a future date.
end
string date
End date of time period, if known and if not ongoing, in format yyyy-mm-dd. Can be a future date.
use
string

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.
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 will not appear on the PDS, but the address used for it may.
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 will not be returned due to FHIR conformance constraints.

Max items: 5
string
postalCode
string
Postal code of the address.
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.