{"openapi":"3.0.0","info":{"version":"v1.3.370-alpha","title":"Personal Demographics Service (FHIR) API","description":"## Overview \nUse this API to access the [Personal Demographics Service (PDS)](https://digital.nhs.uk/services/demographics) - the national electronic database of NHS patient details such as name, address, date of birth, related people, registered GP practice and NHS number.\n\nThis API has three [access modes](#overview--access-modes), which give you different functionality and ways of authenticating. Depending on your access mode, you can:\n* search for patients\n* get patient details\n* update patient details\n* get a patient's related people\n* get patient coverage\n* update patient coverage\n* create a record for a new patient (except for GPs - see below)\n\nYou cannot currently use this API to:\n* create a new record for a birth - use [PDS HL7 V3 API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-hl7-v3)\n* receive birth notifications - use [PDS HL7 V3 API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-hl7-v3) or [PDS Notifications FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-notifications-fhir) \n* register a new patient at a GP Practice - use [NHAIS GP Links API](https://digital.nhs.uk/developer/api-catalogue/nhais-gp-links)\n* receive patient death notifications - use [PDS Notifications FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-notifications-fhir) \n* receive notifications about a patient's change of address - use [PDS Notifications FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-notifications-fhir) \n* receive notifications about a patient's change of GP - use [PDS Notifications FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-notifications-fhir) \n* receive notifications about any PDS record change - use [PDS Notifications FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-notifications-fhir) \n\nYou can read and update the following data:\n* NHS number (read only)\n* name\n* administrative gender\n* addresses and contact details\n* birth information\n* death information\n* registered GP\n* nominated pharmacy\n* dispensing doctor pharmacy\n* medical appliance supplier pharmacy\n* related people, such as next of kin (read only)\n* patient coverage data\n\n### Patients included in PDS\nRegardless of nationality, or where they live now, PDS includes all patients who have ever been registered with a GP practice, or treated by a health or care organisation (even as a visitor or migrant) in England, Wales, the Isle of Man, or in a UK Defence Medical Services unit anywhere in the world. \n\nAll patients in PDS have an NHS number which is unique. The 10-digit NHS number is used in England, Wales, the Isle of Man, Scotland and Northern Ireland, but not the Channel Islands. Scotland and Northern Ireland have their own distinct number ranges.\n\n## Who can use this API\nThis API can only be used where there is a [legal basis](https://digital.nhs.uk/services/demographics/access-data-on-the-personal-demographics-service) to do so. Make sure you have a valid use case before you go too far with your development. You must demonstrate you have a [valid use case](https://digital.nhs.uk/services/demographics/access-data-on-the-personal-demographics-service) as part of digital onboarding. \n\n[You must do this before you can go live](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir#overview--onboarding).\n\n### Who can access PDS records\nHealth and care organisations in England and the Isle of Man can access PDS records. Legitimate direct care examples include NHS organisations delivering healthcare, local authorities delivering care, third sector and private sector health and care organisations, and developers delivering systems to health and care organisations. \n\nHealth and care organisations in Wales access their own version of PDS called the Welsh Demographics Service (WDS) which is connected to PDS behind the scenes. \n\nPatients who receive health and social care or make use of NHS services in England, Wales and the Isle of Man can access their own PDS records. \n\nHealth and care organisations and patients in Scotland, Northern Ireland and the Channel Islands access their own equivalents of PDS.\n\n### Existing API users\nTo find out which healthcare software development organisations and products are already using this API, see [PDS FHIR API - integrated products](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/integrated-products).\n\n## Access modes\nThis API has three access modes. They are: \n* healthcare worker access \n* patient access \n* restricted access \n\n### Healthcare worker access \nIf the end user is a healthcare worker then you must use this access mode. Use this access mode to: \n* search for patients and be able to present a list of matches for the user to choose from \n* get patient details \n* update patient details \n* get a patient's related people\n* create a record for a new patient (except for GPs)\n\nThis access mode is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present, authenticated and authorised. \n\nThe end user must be: \n* a healthcare worker \n* strongly authenticated, using CIS2 Authentication, to [authenticator assurance level AAL2 or AAL3](https://digital.nhs.uk/services/care-identity-service/applications-and-services/cis2-authentication/authenticators#authenticator-levels)\n* authorised, using [national role-based access control (RBAC)](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/national-rbac-for-developers)\n\nTo use this access mode, use one of the following security patterns:\n\n|\tSecurity pattern\t\t |\tTechnical details\t |\tAdvantages | Disadvantages |\n|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---------------------------------------------------------| -------------------------------------------------------------------------|---------------------------------------------------------------------------|\n|[NHS CIS2 - combined authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-combined-authentication-and-authorisation) |OAuth 2.0 authorisation code flow with API key and secret |No need to integrate and onboard separately with NHS CIS2. |No access to user information.
Not recommended for use in GP software. |\n|[NHS CIS2 - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation) |OAuth 2.0 token exchange with signed JWT |Gives access to user information.
Recommended for use in GP software. |Need to integrate and onboard separately with NHS CIS2. |\n\nThis access mode is [in beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status).\n\n### Patient access \nIf the end user is a patient then you must use this access mode. Use this access mode to: \n* get the patient's own details \n* update the patient's own details (limited)\n* get the patient's related people\n* get patient coverage (for specific use cases only)\n* update patient coverage (for specific use cases only)\n\nThis access mode is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present, authenticated and authorised. \n\nThe end user must be: \n* a patient who receives health and social care or makes use of NHS services \n* strongly authenticated, using [NHS login](https://digital.nhs.uk/services/nhs-login)\n\nTo use this access mode, use one of the following security patterns:\n\n|\tSecurity pattern\t\t |\tTechnical details\t |\tAdvantages\t | Disadvantages |\n|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------| ------------------------------------------------------------|---------------------------------------------------------|\n|[NHS login - combined authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-combined-authentication-and-authorisation) |OAuth 2.0 authorisation code with API key and secret |No need to integrate and onboard separately with NHS login. |No access to user information. |\n|[NHS login - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation) |OAuth 2.0 token exchange with signed JWT |Gives access to user information. |Need to integrate and onboard separately with NHS login. |\n\nPatient access mode users must be authenticated to a high proofing level (P9) and to one of the following [vectors of trust](https://nhsconnect.github.io/nhslogin/vectors-of-trust/): \n* P9.Cp.Cd\n* P9.Cp.Ck\n* P9.Cm\n\nThis access mode is [in beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status).\n\n### Restricted access\nYou must only use this access mode if you need to: \n* search for a patient and get a single match result returned \n* get a patient's details\n* get a patient's related people\n\nThis access mode is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate and authorise the calling application but not the end user. \n\nThis access mode is not designed to be accessed by an end user. You might use this access mode as part of a back-end process to: \n* retrieve NHS numbers for data flowing from one system to another\n*\tverify an NHS number\n*\tget a patient's registered GP practice or contact details\n\nTo use this access mode, use this security pattern:\n* [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)\n\nAvailable in production ([stable](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status))\n\n## Status and roadmap\nThis API is [in production](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\nHealthcare worker and patient access modes are [in beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses).\n\nThe [Personal Demographics Service (PDS) ](https://digital.nhs.uk/services/personal-demographics-service/pds-roadmap-and-strategy) roadmap shows the planned changes for PDS products, including the PDS FHIR API. \n\n## Service level\n\nThis API is a platinum service, meaning it is operational and supported 24 hours a day, 365 days a year.\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Rate limits\n\nThe default rate limit is 5TPS (Transactions Per Second), per app. If you require a higher rate limit please [contact us](https://digital.nhs.uk/developer/help-and-support). or raise this during the onboarding process.\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#basic-rest).\n\nIt conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/), except that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.\n\nIt includes some country-specific FHIR extensions, which are built against [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically [UK.core.r4 1.0.0](https://simplifier.net/packages/uk.core.r4/1.0.0).\n\nYou do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.\nIn particular:\n- resource names are capitalised and singular, for example `/Patient` not `/patients`\n- array names are singular, for example `line` not `lines` for address lines\n- data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object\n\nThere are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration.\n\n## Network access\nThis API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).\n\nTo use this API with [NHS smartcards](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/nhs-smartcards-for-developers), the end user needs an HSCN connection, although internet-facing alternatives to smartcards are available.\n\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n \n## Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n* 400 to 499 if it failed because of a client error by your application\n* 500 to 599 if it failed because of an error on our server\n\nErrors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n\nYour API-calling application should have a mechanism to automatically try again, for example by giving status information to your end user, before giving up. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#error-handling) for more information about error handling.\n\n## Open source\nYou might find the following [open source](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#open-source) resources useful:\n\n| Resource | Description | Links |\n|---------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------|\n| PDS FHIR API | Source code for the API proxy, sandbox and specification. | [GitHub repo](https://github.com/NHSDigital/personal-demographics-service-api) |\n| FHIR libraries and SDKs | Various open source libraries for integrating with FHIR APIs. | [FHIR libraries and SDKs](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) |\n| nhs-number | Python package containing utilities for NHS numbers including validity checks, normalisation and generation. | [GitHub repo](https://github.com/uk-fci/nhs-number) \\| [Python Package index](https://pypi.org/project/nhs-number/) \\| [Docs](https://nhs-number.uk-fci.tech/) |\n\nWe currently don't have any open source client libraries or sample code for this API and the source code for the PDS FHIR back end (the Core Spine source code) is not currently in the open. If you think this would be useful, [contact us](https://digital.nhs.uk/developer/help-and-support).\n\n## Environments and testing\n\n| Environment | Base URL |\n| ----------------- | ---------------------------------------------------------------------- |\n| Sandbox | `https://sandbox.api.service.nhs.uk/personal-demographics/FHIR/R4/` |\n| Integration test | `https://int.api.service.nhs.uk/personal-demographics/FHIR/R4/` |\n| Production | `https://api.service.nhs.uk/personal-demographics/FHIR/R4/` |\n\n### Sandbox testing\nOur [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):\n* is for early developer testing\n* only covers a limited set of scenarios\n* is stateless, so does not actually persist any updates\n* is open access, so does not allow you to test authorisation\n\nFor details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n\n### Integration testing\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n* is for formal integration testing\n* is stateful, so persists updates\n* includes authorisation, with options for user-restricted access (with or without [smartcards](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/nhs-smartcards-for-developers) and application-restricted access\n \nFor read-only testing, you can either use our [PDS FHIR API test data packs](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/pds-fhir-api-test-data) or set up your own test data.\n\nTo test updating patient details, you must set up your own test data.\n\nFor more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).\n\n### Production smoke testing\nYou must not use real patient data for smoke testing in the production environment.\n\nRather, use our [production test patient](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/pds-fhir-api-test-data#production-smoke-testing).\n\n## Onboarding\nYou 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.\n\nAs part of this process, you need to demonstrate your technical conformance to the requirements for this API. For more details according to your access mode, see:\n* [PDS FHIR API technical conformance - application-restricted access mode](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/pds-fhir-technical-conformance---application-restricted-access-mode)\n* [PDS FHIR API technical conformance - healthcare worker access mode](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/pds-fhir-technical-conformance---healthcare-worker-access-mode)\n\nYou also need to demonstrate that you can manage risks. This might impact the design of your software. For details, see [Onboarding support information](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/onboarding-support-information).\n\nTo understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding). \n\n
\n
\n
\n
\n \n \"\"\n \n
\n
\n
\n

To get started, sign in or create a developer account, then select 'product onboarding'.

\n
\n
\n
\n\n## Related APIs\n\nThe following APIs are related to this API:\n\n### Personal Demographics Service (PDS) HL7 V3 API\nUse [PDS HL7 V3 API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-hl7-v3) if you want to use functions that are not yet available on the FHIR API, such as creating a new record for a birth or receiving birth notifications. For birth notifications, another option is [PDS Notifications - FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-notifications-fhir).\n\nOnce our roadmap is complete, PDS HL7 V3 API will become redundant. \n\n### Personal Demographics Service (PDS) Notifications - FHIR API\nUse [PDS Notifications - FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-notifications-fhir) to subscribe to be notified of a set of patient record changes, including any record update, birth, death, change of address and change of GP.\n\n### Organisation Data Service FHIR API \nUse [Organisation Data Service FHIR API](https://developer.nhs.uk/apis/ods/) to get full details for the organisations related to the patient, such as their registered GP or nominated pharmacy.\n\n### Ordnance Survey (OS Places) API \nUse [Ordnance Survey (OS Places) API](https://digital.nhs.uk/developer/api-catalogue/ordnance-survey-places-api) to identify, look up and verify addresses prior to a PDS update.\n\n## Contact us\nFor help and support connecting to our APIs and to join our developer community, see [Help and support building healthcare software](https://digital.nhs.uk/developer/help-and-support). \n","contact":{"name":"Personal Demographics Service FHIR API Support","url":"https://digital.nhs.uk/developer/help-and-support","email":"ssd.nationalservicedesk@nhs.net"}},"servers":[{"url":"https://sandbox.api.service.nhs.uk/personal-demographics/FHIR/R4","description":"Sandbox environment."},{"url":"https://int.api.service.nhs.uk/personal-demographics/FHIR/R4","description":"Integration test environment."},{"url":"https://api.service.nhs.uk/personal-demographics/FHIR/R4","description":"Production environment."}],"paths":{"/Patient":{"parameters":[{"in":"header","name":"Authorization","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\n\nRequired in all environments except sandbox.\n","required":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"in":"header","name":"NHSD-Session-URID","description":"\nThe user role ID (URID) for the current session. Also known as a user role profile ID (URPID).\n\nThis header is optional.\n\nIn Application-restricted and Patient access mode this header is ignored.\n\nIn Healthcare worker access mode if you send this header it must be valid for the logged-in user. See [determine the user's role](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation#step-9-determine-the-user-s-role) for guidance.\n","required":false,"schema":{"type":"string","pattern":"^[0-9]+$","example":"555254240100"}},{"in":"header","name":"X-Request-ID","required":true,"description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\n\nMust be a universally unique identifier (UUID) (ideally version 4).\n\nMirrored back in a response header.\n\nThis is a mandatory header.\n\nIf you re-send a failed request, use the same value in this header.\n","schema":{"type":"string","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"}},{"in":"header","name":"X-Correlation-ID","required":false,"description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\n\nMirrored back in a response header.\n","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"in":"header","name":"NHSD-End-User-Organisation-ODS","required":false,"description":"The ODS code of the user.\n\nMandatory for client applications which service multiple end user organisations (EUO). This will allow the calls to be attributed to the correct EUO.\n","schema":{"type":"string","example":"Y12345"}}],"get":{"summary":"Search for a patient","operationId":"search-patient","description":"## Overview\nUse this endpoint to search for a patient in PDS.\n\nYou can search using various combinations of:\n * given name\n * family name\n * gender\n * postcode\n * date of birth - which can be a range\n * date of death - which can be a range\n * registered GP practice\n * email address\n * phone number\n \nThere are various search options, such as fuzzy search, exact match, history and wildcards. Wildcard searches using the PDS FHIR API return information differently to the FHIR framework standards. \n\nThe behaviour of this endpoint depends on which access mode you are using:\n\n| Access mode | Behaviour |\n| ------------------------------ | ------------------------------------------ |\n| Application-restricted access | Only a single unique match returned |\n| Healthcare worker access | Up to 50 matching patient records returned |\n| Patient access | Not yet available |\n\n\n\n## Patient data returned\nThe patient data returned on a search is not the full set of data that is returned on a retrieval by NHS number. The following data is included:\n* NHS number\n* names - usual, nickname and temporary\n* gender\n* birth information, apart from place of birth\n* death information\n* address - home address\n* contact details\n* registered GP\n* restricted patient flag\n\nThe following data is excluded:\n* place of birth\n* names, apart from usual, nickname and temporary \n* addresses, apart from home address\n* pharmacy details\n* communication details\n* contact preferences\n\n### Restricted patients\nSome patients are tagged as [restricted](https://digital.nhs.uk/services/demographics/restricting-access-to-a-patients-demographic-record) and are sometimes known as sensitive patients. When performing a search, restricted patients can be returned; however, location sensitive fields such as `address`, `telecom`, `contact` and `generalPractitioner` are removed.\n\nIf `address-postalcode`, `address-postcode`, or `general-practitioner` are included in the search parameters, no restricted patients are returned even if a match is identified.\n\nThe restricted flag can be found in the data under `meta/security` on the patient resource.\n\n### Invalidated patients\nSome patients are marked as invalidated in PDS - also known as `redacted` in FHIR terminology. Invalidated patient records are not returned in search results.\nIf an invalidated patient record has been superseded, the superseding record is returned.\n\n## Scoring\nEvery matched patient in the result list includes a score to indicate how closely the patient matched the search parameters.\n\nA score of 1.0 indicates an exact match. A score of less than 1.0 indicates a partial match.\n\nThe result list is sorted in descending score order - best match first.\n\nUse the `_exact-match` query parameter to return exact matches only - where the score is 1.0.\n\n## Clinical safety and privacy\nThis endpoint can return multiple matching patients for a given search, including partial matches.\n\nEnsure that you design your software to minimise the following risks:\n* 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 clinical data\n* the end user has access to patients' personal data, so there is a risk to patient privacy\n\nNote that:\n* we record an access request in our audit trail for all patients matched in a PDS search\n* it is almost certainly a good idea to display search results in descending score order - best match first\n\nPlease consider the information your application returns to users. For example a patient's temporary address can be used to perform a successful search. The home address will be included in the response. For citizen facing services please be aware of this behaviour and do not present a different address to the patient, unless they are logged in at a sufficiently high proof point.\n\n## Search options\nThe following sections explain the various search options.\nWhich options you choose depends very much on your use case, and getting it right is really important.\nIf you need help, [contact us](https://digital.nhs.uk/developer/help-and-support).\n\n### Application-restricted access mode\nIn this access mode, you only get a single matching patient record, and only if it's a unique match.\n\nUse search options that are likely to find a unique match. In our experience, the following is a good starting point:\n * search on given name, family name, postcode and date of birth - this combination should uniquely identify a patient\n * for given name, use the first three characters and a wildcard, for example to search for `Annabel`, use `Ann*` - this caters for different name spellings and abbreviations\n * for postcode, use the first two characters and a wildcard, for example to search for `LS11 6AD`, use `LS*` - this caters for people who have moved locally but not updated PDS\n * use a non-fuzzy search - this reduces the chance of multiple matches\n * use a non-exact match - an exact match does not work with wildcards\n * include history - this increases the chance of a match\n\nFor more details, see the following sections.\n\n### Healthcare worker access mode\nIn this access mode - where the end user is a strongly authenticated healthcare worker - you can get up to 50 matching patient records.\nThis allows the end user to choose the best match.\n\nUse search parameters that are relevant to your use case - for example date of death is not always appropriate.\n\nTo protect patient privacy, design your search to minimise the number of matching patients.\nFor example, you could:\n * encourage users to enter as many search parameters as they can\n * force users to try a non-fuzzy search first and then only offer a fuzzy search if they cannot find the patient\n\nFor more details, see the following sections.\n\n### Non-fuzzy search\nA non-fuzzy search:\n * allows wildcards in names and postcodes\n * does not match homophones or transposed names\n * can optionally search history, such as previous names and addresses\n\nIt is less likely to return multiple matches than a fuzzy search, so is more suitable for finding a unique match.\n\nThe minimum search parameters are:\n * family name - which can include wildcards\n * date of birth - which can be a range\n \n### Fuzzy search\nA fuzzy search:\n * matches common homophones, such as `Smith` and `Smythe`, using the [Soundex](https://en.wikipedia.org/wiki/Soundex) algorithm\n * checks for transposed names, such as `Adam Thomas` and `Thomas Adam`\n * always searches history, such as previous names and addresses\n\nIt is more likely to include multiple matches than a non-fuzzy search, so is not ideal for finding a unique match.\n\nIt is also more likely to include false positives - other patients that match the search criteria.\nTherefore, for privacy reasons, it is better to use it only if a non-fuzzy match has failed.\n\nYou must use one of the following search parameter combinations:\n * given name, family name and date of birth\n * family name, date of birth, gender and postcode\n * given name, date of birth, gender and postcode\n\nIf you include the date of death or registered GP practice query parameters, they are not used in the search. However they do affect the patient's matching score - a mismatch reduces the returned score.\n\n### History\nPDS holds historic information, including previous names and addresses.\n\nA fuzzy search always includes history. For a non-fuzzy search, you can request to include history.\n\nSearching history can match patients when only a previous name or address is known, or if a patient provides a previous name or address on the assumption that their record hasn't been updated. When a search done on historic data results in a match, the patient's current data will be returned in the response message, not the historic data used to identify the match.\n\n### Exact match\nYou can request an exact match.\nThis might be useful if you are verifying an NHS number against details you already believe to be correct.\nIt is unlikely to work well with wildcards or fuzzy search.\n\n### Names\nMatching names can be difficult when a person has multiple given names, including:\n * given names that include middle names, such as in `Jane Anne Smith`\n * [compound given names](https://en.wikipedia.org/wiki/Given_name#Compound), such as in `John Paul Smith`\n\nMatching names can also be difficult when a name has:\n * multiple or double-barrelled surnames, such as in `Michael Smith-Jones`\n * homophones, such as `Smith` and `Smythe` or `Ann` and `Anne`\n * abbreviated names, such as `Bob` instead of `Robert`\n * transposed names, such as `Adam Thomas` instead of `Thomas Adam`\n * previous names, such as maiden names\n * special characters such as in `O'Reilly`, `Jones-Smith` or `Kociński`\n * spelling mistakes, either in the search criteria or in PDS\n\nTo deal with some of these issues:\n * we search across all types of name - usual, nickname and temporary\n * a fuzzy search matches homophones, transposed names and previous names\n * for a non fuzzy search, you can optionally search previous names and use wildcards. Wildcards will match against the start of the name string, for example the start of a compound name.\n\n### Gender\nPDS has four options for gender - `male`, `female`, `other` and `unknown`.\nThis is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n\nIn these cases, searching by gender might not find the patient.\nThese are edge cases but are important to consider because gender can be a sensitive issue for the people in question.\n\nIn general, we recommend not including gender as a search parameter.\n \n### Date of birth and death\nSometimes, the exact date of birth or death is not known when doing a search.\nSometimes, the date of birth or death is not accurate in PDS.\nFor example, if only the year of birth is known, the day and month of birth might be recorded as the first of January - for example, `01/01/1932`.\n\nIn such cases, searching a range of dates can help. This can result in multiple matches, so might not work well when searching for a unique match.\n\n### Postcode\nPeople sometimes move locally, meaning the postcode in PDS is out of date, but does at least match on the first two characters.\n\nSearching for the first two characters of the postcode and a wildcard can work well. For example, to search for `LS11 6AD`, use `LS*`.\nThis is only possible for a non-fuzzy search.\n\nThis can result in multiple matches, but it has been known to work well in some cases - even for unique matches.\n\n### General practitioner\nThis is an ODS code. If you use it, it must match exactly.\n\n### Phone number and email address\nIf you use phone number and/or email address, only exact matches will be returned.\n * Wildcards are not supported\n * Only current data will be searched, unless a history search is also requested in which case the match will take into account both current and historic data\n * Email addresses are not case-sensitive.\n\n### Differences between the matching types at a glance\n\n| Search | Non-fuzzy matching | Fuzzy matching |\n| ----------------------------------------| --------------------------------------------------| ----------------------------------------------------------------------------------|\n| History | Optional | Always |\n| Names | Allows wildcards | Matches homophones, transposed names and previous names. Does not allow wildcards.|\n| Postcode | Allows wildcards | Does not allow wildcards |\n\n## Sandbox testing\nYou can test the following scenarios in our sandbox environment:\n\n| Scenario | Request | Response |\n| ----------------------------------------| ----------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------------------------------------------------------------------------------------|\n| Basic search with phone & email positive| `family`=`Smith`, `gender`=`female`, `birthdate`=`eq2010-10-22`, `email`=`jane.smith@example.com`, `phone`=`01632960587` | HTTP Status 200 with single search result. |\n| Basic search with phone & email negative| `family`=`Smith`, `gender`=`female`, `birthdate`=`eq2010-10-22`, `email`=`deb.trotter@example.com`, `phone`=`0121111111` | HTTP Status 200 with no search results. | \n| Wildcard search without phone/email | `family`=`Sm*`, `gender`=`female`, `birthdate`=`eq2010-10-22` | HTTP Status 200 with search result of two. |\n| Wildcard search with email and phone | `family`=`Sm*`, `gender`=`female`, `birthdate`=`eq2010-10-22`, `email`=`jane.smith@example.com`, `phone`=`01632960587` | HTTP Status 200 with single search result. |\n| Search with limited results | `family`=`Sm*`, `gender`=`female`, `birthdate`=`eq2010-10-22`, `email`=`jane.smith@example.com`, `phone`=`01632960587`, `_max-results`=`1` | HTTP Status 200 with single search result. |\n| Search with date range | `family`=`Smith`, `gender`=`female`, `birthdate`=`ge2010-10-21`, `birthdate`=`le2010-10-23`, `email`=`jane.smith@example.com`, `phone`=`01632960587` | HTTP Status 200 with single search result. |\n| Fuzzy search with phone and email | `family`=`Smith`, `given`=`Jane`, `gender`=`female`, `birthdate`=`eq2010-10-22`, `email`=`jane.smith@example.com`, `phone`=`01632960587`, `_fuzzy-match`=`true` | HTTP Status 200 with single search result. |\n| Fuzzy search without phone or email | `family`=`Smith`, `given`=`Jane`, `gender`=`female`, `birthdate`=`eq2010-10-22`, `_fuzzy-match`=`true` | HTTP Status 200 with single search result. |\n| Restricted patient search | `family`=`Smythe`, `given`=`Janet`, `gender`=`female`, `birthdate`=`eq2005-06-16`, `email`=`janet.smythe@example.com`, `phone`=`01632960587` | HTTP Status 200 with single search result with restricted data omitted. |\n| Compound name search | `family`=`Smith`, `given`=`John Paul`, `given`=`James`, `gender`=`male`, `birthdate`=`eq2010-10-22`, `email`=`johnp.smith@example.com`, `phone`=`01632960587` | HTTP Status 200 with single search result. |\n| Unsuccessful search | Any other valid search query parameters | HTTP Status 200 with a warning that the search parameters do not have an example response.|\n| Valid/invalid search criteria | `family`=`Sm*`, `gender`=`female`, 'invalidParam'='123', `birthdate`=`eq2010-10-22`, `email`=`j.smith@example.com`, `phone`=`0163` | HTTP Status 400 with problem description. |\n| Unsuccessful search on email/phone only | `email`=`j.smith@example.com`, `phone`=`0163` | HTTP Status 400 with problem description. |\n| Invalid date format | `birthdate` or `death-date` query parameters with values not in format `YYYY-MM-DD` | HTTP Status 400 with problem description. |\n| Too few search parameters | Any invalid combination of query parameters | HTTP Status 400 with problem description. |\n| Missing X-Request-ID | `id`=`9000000009` (or any other valid NHS number) | HTTP Status 400 with problem description. |\n\nYou can try out the sandbox by selecting the 'Try' button at the end of the schema.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n","parameters":[{"name":"_fuzzy-match","description":"A fuzzy search is performed, including checks for homophones, transposed names and historic information.\n\nYou cannot use wildcards with a fuzzy search.\n","example":false,"in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"_exact-match","description":"The search only returns results where the `score` field is 1.0. Use this with care - it is unlikely to work with fuzzy search or wildcards.","example":false,"in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"_history","description":"The search looks for matches in historic information such as previous names and addresses.\n\nThis parameter has no effect for a fuzzy search, which always includes historic information.\n","example":false,"in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"_max-results","description":"The maximum number of matching patients to return. For healthcare worker access, this must be between 1 and 50, and the default is 50.\nFor application-restricted access, this must be 1, and the default is 1.\nIf too many patients match the search criteria, we return a `TOO_MANY_MATCHES` error.\n","example":1,"in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"family","description":"The patient's family name (surname).\n\nNot case sensitive. Max 35 characters.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n","examples":{"simple":{"value":"Smith","summary":"Matches Smythe if `_fuzzy-match` is specified."},"wildcarded":{"value":"Sm*t*","summary":"Wildcards must contain at least two characters, this matches Smith, Smythe"}},"in":"query","required":false,"schema":{"type":"string"}},{"name":"given","description":"The patient's given names, including their first and middle names.\n\nNot case sensitive. Max 35 characters.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nWildcard searches will match the start of the first given name and not subsequent given names, for example the given names \"Alan Michael\" can be searched with \"Ala*\" but not \"Mic*\".\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n\nA patient may have more than one given name, for example because they have a first name and a middle name.\nSpecify multiple given names by repeating this parameter.\nTo search for `Jane Anne Smith` use `given=Jane&given=Anne&family=Smith`.\n\nThe first name may be a [compound name](https://en.wikipedia.org/wiki/Given_name#Compound), for example `John Paul`.\nTo search for `John Paul James Smith` (where `John Paul` is the first name, `James` is the middle name, and `Smith` the family name) use `given=John%20Paul&given=James&family=Smith`.\n\nIt is not necessary to specify subsequent given names, and doing so may impact your search results if they are not recorded in the PDS.\n","example":"Jane","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"gender","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.","example":"female","in":"query","required":false,"schema":{"type":"string","enum":["male","female","other","unknown"],"example":"female"}},{"name":"birthdate","in":"query","description":"Date of birth in the format `yyyy-mm-dd`. To specify a range, use `birthdate=geyyyy-mm-dd&birthdate=leyyyy-mm-dd`.","examples":{"simple":{"value":["eq2010-10-22"],"description":"Exact match date"},"rangege":{"value":["ge2010-10-22"],"description":"Greater than or equals match, which matches 2010-10-22 or 2010-10-23"},"rangele":{"value":["le2010-10-22"],"description":"Less than or equals match, which matches 2010-10-22 or 2010-10-21"}},"required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"death-date","in":"query","description":"Date of death in the format `yyyy-mm-dd`. To specify a range, use `death-date=geyyyy-mm-dd&death-date=leyyyy-mm-dd`.\n\nFor a fuzzy search, this is ignored for matching but included in the score calculation.\n","examples":{"simple":{"value":"eq2010-10-22","description":"Exact match date"},"rangege":{"value":"ge2010-10-22","description":"Greater than or equals match which matches 2010-10-22 or 2010-10-23"},"rangele":{"value":"le2010-10-22","description":"Less than or equals match, which matches 2010-10-22 or 2010-10-21"}},"required":false,"schema":{"type":"string","format":"date"}},{"name":"address-postalcode","description":"The postcode of any of the patient's known addresses.\n\nNot case sensitive.\nSpaces are ignored, for example `LS16AE` and `LS1 6AE` both match `LS1 6AE`.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n","examples":{"simple":{"value":"LS1 6AE","summary":"Spaces ignored, would match LS16AE"},"wildcarded":{"value":"LS1*","summary":"Matches 'LS16AE', 'LS1 6AE' and 'LS1 6AB'"}},"in":"query","required":false,"schema":{"type":"string"}},{"name":"address-postcode","description":"**N.B. that address-postcode will be deprecated in the future, address-postalcode should be used instead. \nIf both address-postcode and address-postalcode are provided, an INVALID_SEARCH_DATA error will be returned.**\nThe postcode of any of the patient's known addresses.\n\nNot case sensitive.\nSpaces are ignored, for example `LS16AE` and `LS1 6AE` both match `LS1 6AE`.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n","examples":{"simple":{"value":"LS1 6AE","summary":"Spaces ignored, would match LS16AE"},"wildcarded":{"value":"LS1*","summary":"Matches 'LS16AE', 'LS1 6AE' and 'LS1 6AB'"}},"in":"query","required":false,"schema":{"type":"string"}},{"name":"general-practitioner","description":"The Organisation Data Service (ODS) code of the patient's registered GP practice.\n\nNot case sensitive.\nFor a fuzzy search, this is ignored for matching but included in the score calculation.\n","example":"Y12345","in":"query","required":false,"schema":{"type":"string"}},{"name":"email","description":"Email address\n","example":"jane.smith@example.com","in":"query","required":false,"schema":{"type":"string"}},{"name":"phone","description":"Phone number\n","example":"01632960587","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A completed search. This might contain zero, one, or many matching patients, or it might contain a 'TOO_MANY_MATCHES' error.\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | -------------------------------------------------------------------------- |\n| 200 | TOO_MANY_MATCHES | Too many matches were found - user should refine their search parameters.\t|\n","headers":{"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"Bundle"},"type":{"type":"string","description":"FHIR Bundle Type.","default":"searchset"},"timestamp":{"type":"string","description":"Time the search was performed.","format":"datetime","example":"2019-12-25T12:00:00+00:00"},"total":{"type":"integer","description":"Number of resources returned in search.","example":1},"entry":{"type":"array","description":"A list of matched patients. Empty if none found. The patients are ordered by match score, best first. A maximum of 50 patients are returned.\n","items":{"type":"object","properties":{"fullUrl":{"type":"string","description":"Absolute URL of the resource described in this item.","example":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009"},"search":{"type":"object","properties":{"score":{"description":"Search score from 0.0 to 1.0.","type":"number","minimum":0,"maximum":1,"example":0.75}}},"resource":{"type":"object","additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"id":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"identifier":{"type":"array","description":"Identifier and system of identification used for this Patient.","maxItems":1,"items":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","description":"System identifier belongs to.","default":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"extension":{"type":"array","description":"FHIR extensions.","items":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}}}}}},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The NHS Digital assigned version of the patient resource.","example":"2"},"security":{"type":"array","description":"The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:\n* U - unrestricted. All available data is returned.\n* R - restricted. Any sensitive data around the patient's location, so `address`, `generalPractitioner` and `telecom`, are removed from the response.\n* REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.\n","maxItems":1,"items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the value set specification.","example":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality"},"code":{"type":"string","description":"Code defined by the system value set.","enum":["U","R","V","REDACTED"],"example":"U"},"display":{"type":"string","description":"Representation defined by the system.","enum":["unrestricted","restricted","redacted"],"example":"unrestricted"}}}}}},"name":{"type":"array","description":"List of names associated with the patient.\nThis is only fully populated on a retrieval or a successful update, only the `usual`, `nickname` and `temp` names are returned on a search. \n","minItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"multipleBirthInteger":{"type":"integer","minimum":1,"maximum":9,"description":"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.\n\nThere are two other valid values; `8` meaning `Not applicable` and `9` meaning `Not known`.\n","example":1},"deceasedDateTime":{"description":"The date and time in UTC on which a person died or is officially deemed to have died, if applicable and known.\n\nIt is a datetime in the format `yyyy-mm-ddTHH:MM:SS+00:00` or `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.\n","example":"2010-10-22T00:00:00+00:00","type":"string","format":"date-time","pattern":"^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T\\d{2}:\\d{2}:\\d{2}\\+00:00)$|^([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]))$"},"address":{"type":"array","description":"List of addresses associated with the patient.\n\nThis is only fully populated on a retrieval or a successful update, only the `home` address is returned on a search.\nWhen a patient tagged as `restricted` is retrieved, all addresses are removed from the response.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient; for example, phone numbers or email addresses.\nWhen a patient tagged as `restricted` is retrieved, all contact points are removed from the response.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"contact":{"type":"array","description":"A list of patient contacts. Only emergency contacts are returned. Any other contacts are returned on the patients `Related Person`.\nWhen a patient tagged as `restricted` is retrieved, all contacts are removed from the response.\n","items":{"title":"Schema for a patient contact.","type":"object","additionalProperties":false,"required":["relationship","telecom"],"properties":{"id":{"type":"string","example":"C123"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"relationship":{"type":"array","description":"The contact relationship wrapper object that holds the details of the relationship to the patient.\n\nThis is only returned when an Emergency Contact number has been set on `telecom`. The only valid code is `C`, which means `Emergency Contact`.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}}},"telecom":{"type":"array","description":"List of Telecom objects on the contact only contains `system` and `value`.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}}}}},"generalPractitioner":{"type":"array","maxItems":1,"description":"General Practice (not practitioner) with which the patient is, or was, registered. Always contains zero or one general practitioner object.\nWhen a patient tagged as `restricted` is retrieved, the General Practice is removed from the response.\n","items":{"description":"General practice (not practitioner) with which the patient is or was registered.","type":"object","required":["identifier"],"properties":{"id":{"description":"Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.","type":"string","example":"254406A3"},"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}}},"extension":{"type":"array","description":"Wrapper array for the patient's death notification status; this is a FHIR extension. Always contains zero or one death notification status object.\n","items":{"anyOf":[{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}}]}}}}}}}}},"example":{"resourceType":"Bundle","type":"searchset","timestamp":"2019-12-25T12:00:00+00:00","total":1,"entry":[{"fullUrl":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009","search":{"score":0.75},"resource":{"resourceType":"Patient","id":"9000000009","identifier":[{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus","version":"1.0.0","code":"01","display":"Number present and verified"}]}}]}],"meta":{"versionId":"2","security":[{"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality","code":"U","display":"unrestricted"}]},"name":[{"id":"123","use":"usual","period":{"start":"2024-01-01","end":"2025-12-31"},"given":["Jane"],"family":"Smith","prefix":["Mrs"],"suffix":["MBE"]}],"gender":"female","birthDate":"2010-10-22","multipleBirthInteger":1,"deceasedDateTime":"2010-10-22T00:00:00+00:00","address":[{"id":"456","period":{"start":"2024-01-01","end":"2025-12-31"},"use":"home","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]}],"telecom":[{"id":"789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"phone","value":"01632960587","use":"home"},{"id":"790","period":{"start":"2019-01-01","end":"2022-12-31"},"system":"email","value":"jane.smith@example.com","use":"home"},{"id":"OC789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"other","value":"01632960587","use":"home","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem","code":"textphone","display":"Minicom (Textphone)"}}]}],"contact":[{"id":"C123","period":{"start":"2024-01-01","end":"2025-12-31"},"relationship":[{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/v2-0131","code":"C","display":"Emergency Contact"}]}],"telecom":[{"system":"phone","value":"01632960587"}]}],"generalPractitioner":[{"id":"254406A3","type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345","period":{"start":"2024-01-01","end":"2025-12-31"}}}],"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","extension":[{"url":"deathNotificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus","version":"1.0.0","code":"2","display":"Formal - death notice received from Registrar of Deaths"}]}},{"url":"systemEffectiveDate","valueDateTime":"2010-10-22T00:00:00+00:00"}]}]}}]}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| 400 | INVALID_SEARCH_DATA\t | Invalid combination of search parameters. For details, see the `diagnostics` field. |\n| 400 | UNSUPPORTED_SERVICE | No search parameters provided. |\n| 400 | MISSING_VALUE | Missing header or query parameter. For details, see the `diagnostics` field. |\n| 400 | INVALID_VALUE | Invalid header or query parameter. For details, see the `diagnostics` field. |\n| 400 | ADDITIONAL_PROPERTIES | Unrecognised query parameter. For details, see the `diagnostics` field. |\n| 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. |\n| 403 | INVALID_VALUE | Multiple results requested when using the API in application-restricted mode. |\n| 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. |\n| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"value","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"INVALID_VALUE","display":"Provided value is invalid"}]},"diagnostics":"Invalid value - 'mal' in field 'gender'"}]}}}}}},"post":{"summary":"Create a record for a new patient","operationId":"create-patient","description":"## Overview\nUse this endpoint to create a record for a new patient, which involves allocating them a new NHS number. Only use this if a search for the patient has been done and no NHS number can be found.\n\nYou should not use this API to create a new record when registering a new patient at a GP Practice. Instead, use the Primary Care Registration Management - NHS Digital (PCRM) system.\n\nYou should not use this API to create a new record at birth.\n\nThis endpoint is only available to users with Healthcare worker access.\n\n## Sandbox test scenarios\n\nYou can test the following scenarios in our sandbox environment.\n\n| Scenario | Request | Response |\n| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- |\n| Patient record is created and allocated a new NHS number\t| Body: One of the provided examples or your own combination

Headers: `Content-Type`=`application/json` | HTTP Status 201 with patient data in response |\n| Single match found\t | Body: Provided example

Headers: `Content-Type`=`application/json` | HTTP Status 200 with matched NHS number in response |\n| Multiple matches found\t | Body: Provided example

Headers: `Content-Type`=`application/json` | HTTP Status 200 with problem description |\n| Missing X-Request-ID | X-Request-ID header missing | HTTP Status 400 with problem description |\n| Invalid X-Request-ID | `X-Request-ID`= `1234` | HTTP Status 400 with problem description |\n\nYou can try out the sandbox by selecting the 'Try' button at the end of the schema.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"description":"Request to create a record for a new patient","type":"object","required":["name","gender","birthDate","address","extension"],"additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"name":{"type":"array","description":"List of names associated with the patient.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"address":{"type":"array","description":"List of addresses associated with the patient.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient, such as phone numbers or email addresses. A patient should only have one instance of each telecom system and use combination on their record at a time. For example, the patient request should not contain multiple work email values in this array.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"extension":{"type":"array","description":"Wrapper array for inclusion of the following extensions, some will not actually persist data to PDS at this time (labelled not persisted):\n* Registering Authority (required)\n* Communication\n* Contact Preference\n* Birth Place (not persisted)\n* Birth Sex (not persisted)\n* Cadaveric Donor (not persisted)\n* Death Notification Status (not persisted)\n* Ethnic Category (not persisted)\n* Residential Status (not persisted)\n* Patient Interpreter Required (not persisted)\n* NHS Number Unavailable Reason (not persisted)\n","items":{"anyOf":[{"type":"object","description":"Definition of registering authority extension.","required":["url","extension"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-RegisteringAuthority FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority"]},"extension":{"type":"array","description":"Array containing exactly one registering authority type object, exactly one organization identifier object, and may include a person identifier object.","minItems":2,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for registering authority type code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `registeringAuthorityType`.","example":"registeringAuthorityType","enum":["registeringAuthorityType"]},"valueCodeableConcept":{"type":"object","description":"Registering Authority Type","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one registering authority type","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of the Registering Authority Type. Always uses the 'UKCore-RegisteringAuthorityType' Code System.","example":"https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType","enum":["https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType"]},"code":{"type":"string","description":"A CodeSystem that identifies the type of the registering authority.","example":"x","enum":["a","b","c","d","e","f","g","h","i","j","k","l","m","n","o","p","q","r","s","t","u","v","w","x","1"]},"display":{"type":"string","description":"Display-friendly representation of the registering authority type.","example":"NHAIS"}}}}}}}},{"type":"object","description":"Wrapper object for registering authority organization identifier.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `organisationIdentifier`.","example":"organisationIdentifier","enum":["organisationIdentifier"]},"valueString":{"type":"string","description":"Wrapper for the registering authority organization identifier.","minLength":2,"maxLength":15}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}},{"type":"object","description":"Wrapper object for place of birth details. This will not be returned on a restricted patient.","required":["url","valueAddress"],"properties":{"url":{"type":"string","description":"Definition of place of birth extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","enum":["http://hl7.org/fhir/StructureDefinition/patient-birthPlace"]},"valueAddress":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string","description":"Town or city of birth.","example":"Manchester"},"district":{"type":"string","description":"County or metropolitan district of birth.","example":"Greater Manchester"},"country":{"type":"string","description":"A coded value for a patient's country of birth.\n\nFrom [ISO 3166-1](http://hl7.org/fhir/valueset-iso3166-1-3.html) plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.\n\nUK Internal Codes:\n* `1` - England\n* `2` - Scotland\n* `3` - Wales\n* `4` - Northern Ireland\n* `7` - Sark\n* `9` - Alderney\n* `10` - Channel Islands\n","example":"GBR"}}}}},{"type":"object","description":"Wrapper object for birth sex details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of birth sex extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-BirthSex","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-BirthSex"]}}},{"type":"object","description":"Wrapper object for cadaveric donor details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of cadaveric donor extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor","enum":["http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor"]}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}},{"type":"object","description":"Wrapper object for ethnic category details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of ethnic category extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory"]}}},{"type":"object","description":"Wrapper object for residential status details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of residential status extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ResidentialStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ResidentialStatus"]}}},{"type":"object","description":"Wrapper object for patient interpreter required details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of patient interpreter required extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-interpreterRequired","enum":["http://hl7.org/fhir/StructureDefinition/patient-interpreterRequired"]}}},{"type":"object","description":"Wrapper object for nhs number unavailable reason details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of nhs number unavailable reason extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberUnavailableReason","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberUnavailableReason"]}}}]}}}},"examples":{"create-patient":{"summary":"Create a patient, no matching records for supplied demographic data","value":{"name":[{"use":"usual","given":["Jane"],"family":"Edwards","prefix":["Mrs"],"period":{"start":"1986-07-01"}}],"address":[{"line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"period":{"start":"2020-01-01"},"postalCode":"LS1 6AE","use":"home","extension":[{"extension":[{"url":"type","valueCoding":{"code":"UPRN","system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"}},{"url":"value","valueString":"203700882517"}],"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"}]}],"gender":"female","birthDate":"1982-07-10","telecom":[{"use":"home","system":"phone","value":"123342","period":{"start":"2020-01-02","end":"2021-01-02"}}],"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority","extension":[{"url":"registeringAuthorityType","valueCodeableConcept":{"coding":[{"system":"https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType","code":"x"}]}},{"url":"organisationIdentifier","valueString":"RGS"}]}],"resourceType":"Patient"}},"single-match":{"summary":"Single matching record found for supplied demographic data","value":{"name":[{"use":"usual","given":["Jane"],"family":"McMatch-Single","prefix":["Mrs"],"period":{"start":"1986-07-01"}}],"address":[{"line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"period":{"start":"2020-01-01"},"postalCode":"BAP 4WG","use":"home","extension":[{"extension":[{"url":"type","valueCoding":{"code":"UPRN","system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"}},{"url":"value","valueString":"203700882517"}],"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"}]}],"gender":"female","birthDate":"1982-07-10","telecom":[{"use":"home","system":"phone","value":"123342","period":{"start":"2020-01-02","end":"2021-01-02"}}],"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority","extension":[{"url":"registeringAuthorityType","valueCodeableConcept":{"coding":[{"system":"https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType","code":"x"}]}},{"url":"organisationIdentifier","valueString":"RGS"}]}],"resourceType":"Patient"}},"multiple-matches":{"summary":"Multiple matching records found for supplied demographic data","value":{"name":[{"use":"usual","given":["Louisa"],"family":"McMatch-Multiple","prefix":["Mrs"],"period":{"start":"1986-07-01"}}],"address":[{"line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"period":{"start":"2020-01-01"},"postalCode":"DN19 7UD","use":"home","extension":[{"extension":[{"url":"type","valueCoding":{"code":"UPRN","system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"}},{"url":"value","valueString":"203700882517"}],"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"}]}],"gender":"female","birthDate":"1982-07-10","telecom":[{"use":"home","system":"phone","value":"123342","period":{"start":"2020-01-02","end":"2021-01-02"}}],"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority","extension":[{"url":"registeringAuthorityType","valueCodeableConcept":{"coding":[{"system":"https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType","code":"x"}]}},{"url":"organisationIdentifier","valueString":"RGS"}]}],"resourceType":"Patient"}}}}}},"responses":{"200":{"description":"New record not created. Single or multiple matches found for supplied demographic data.\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | --------------------------------------------------------------------------------------------------- |\n| 200 | SINGLE_MATCH | Unable to create new patient record. A single matching record found for supplied demographic data. |\n| 200 | MULTIPLE_MATCHES | Unable to create new patient record. Multiple matching records found for supplied demographic data. |\n","headers":{"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"structure","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"MULTIPLE_MATCHES","display":"Multiple matches found"}]},"diagnostics":"Unable to create new patient. Multiple matches found for supplied demographic data."}]}}}},"201":{"description":"New record successfully created. Patient data, including newly allocated NHS number, returned in response.\n","headers":{"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"id":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"identifier":{"type":"array","description":"Identifier and system of identification used for this Patient.","maxItems":1,"items":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","description":"System identifier belongs to.","default":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"extension":{"type":"array","description":"FHIR extensions.","items":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}}}}}},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The NHS Digital assigned version of the patient resource.","example":"2"},"security":{"type":"array","description":"The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:\n* U - unrestricted. All available data is returned.\n* R - restricted. Any sensitive data around the patient's location, so `address`, `generalPractitioner` and `telecom`, are removed from the response.\n* REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.\n","maxItems":1,"items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the value set specification.","example":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality"},"code":{"type":"string","description":"Code defined by the system value set.","enum":["U","R","V","REDACTED"],"example":"U"},"display":{"type":"string","description":"Representation defined by the system.","enum":["unrestricted","restricted","redacted"],"example":"unrestricted"}}}}}},"name":{"type":"array","description":"List of names associated with the patient. This may not appear if the patient is tagged as `restricted` (also known as a sensitive patient). \n","minItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"multipleBirthInteger":{"type":"integer","minimum":1,"maximum":9,"description":"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.\n\nThere are two other valid values; `8` meaning `Not applicable` and `9` meaning `Not known`.\n","example":1},"deceasedDateTime":{"description":"The date and time in UTC on which a person died or is officially deemed to have died, if applicable and known.\n\nIt is a datetime in the format `yyyy-mm-ddTHH:MM:SS+00:00` or `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.\n","example":"2010-10-22T00:00:00+00:00","type":"string","format":"date-time","pattern":"^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T\\d{2}:\\d{2}:\\d{2}\\+00:00)$|^([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]))$"},"address":{"type":"array","description":"List of addresses associated with the patient.\n\nThese are fully populated on a retrieval or a successful update, only the `home` address is returned on a search.\nWhen a patient tagged as `restricted` is retrieved, all addresses are removed from the response.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient, like phone numbers or email addresses. A patient should only have one instance of each telecom system and use combination on their record at a time. For example, to add a new work email value to the record, the existing work email value should be replaced with the new value. When a patient tagged as `restricted` is retrieved, all contact points, like phone numbers or email addresses, are removed from the response.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"contact":{"type":"array","description":"A list of patient contacts. Only emergency contacts are returned and only emergency contacts should be added. Any other contacts should be added to the patients `Related Person`.\nPatients designate here any contact number they desire to be used in case of an emergency.\nNote, 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.\nWhen a patient tagged as `restricted` is retrieved, all contacts are removed from the response.\n","items":{"title":"Schema for a patient contact.","type":"object","additionalProperties":false,"required":["relationship","telecom"],"properties":{"id":{"type":"string","example":"C123"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"relationship":{"type":"array","description":"The contact relationship wrapper object that holds the details of the relationship to the patient.\n\nThis is only returned when an Emergency Contact number has been set on `telecom`. The only valid code is `C`, which means `Emergency Contact`.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}}},"telecom":{"type":"array","description":"List of Telecom objects on the contact only contains `system` and `value`.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}}}}},"generalPractitioner":{"type":"array","maxItems":1,"description":"General Practice (not practitioner) with which the patient is, or was, registered. Always contains zero or one general practitioner object.\nWhen a patient tagged as `restricted` is retrieved, the General Practice is removed from the response.\n","items":{"description":"General practice (not practitioner) with which the patient is or was registered.","type":"object","required":["identifier"],"properties":{"id":{"description":"Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.","type":"string","example":"254406A3"},"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}}},"managingOrganization":{"description":"The managing organization of a de-registered patient. This will not be returned when the reason for de-registration is death.","type":"object","required":["identifier"],"properties":{"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}},"extension":{"type":"array","description":"Wrapper array for the patient's pharmacies, death notification status, communication details, contact preferences and place of birth; these are all FHIR extensions.\nAlways 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.\nWhen a patient tagged as `restricted` is retrieved, the pharmacy and birth place extensions are removed from the response.\n","items":{"anyOf":[{"type":"object","description":"Wrapper object for the patient's nominated pharmacy. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-NominatedPharmacy FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy"]},"valueReference":{"type":"object","description":"Reference to a pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's nominated pharmacy organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the nominated pharmacy, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y12345"}}}}}}},{"type":"object","description":"Wrapper object for the patient's dispensing doctor. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-DispensingDoctor FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization"]},"valueReference":{"type":"object","description":"Reference to a GP practice pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's dispensing doctor organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the dispensing doctor, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y23456"}}}}}}},{"type":"object","description":"Wrapper object for the patient's medical appliance supplier. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-MedicalApplianceSupplier FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier"]},"valueReference":{"type":"object","description":"Reference to medical appliance supplier pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's medical appliance supplier organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the medical appliance supplier, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y34567"}}}}}}},{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for place of birth details. This will not be returned on a restricted patient.","required":["url","valueAddress"],"properties":{"url":{"type":"string","description":"Definition of place of birth extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","enum":["http://hl7.org/fhir/StructureDefinition/patient-birthPlace"]},"valueAddress":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string","description":"Town or city of birth.","example":"Manchester"},"district":{"type":"string","description":"County or metropolitan district of birth.","example":"Greater Manchester"},"country":{"type":"string","description":"A coded value for a patient's country of birth.\n\nFrom [ISO 3166-1](http://hl7.org/fhir/valueset-iso3166-1-3.html) plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.\n\nUK Internal Codes:\n* `1` - England\n* `2` - Scotland\n* `3` - Wales\n* `4` - Northern Ireland\n* `7` - Sark\n* `9` - Alderney\n* `10` - Channel Islands\n","example":"GBR"}}}}},{"type":"object","description":"An extension to carry the reason a PDS record has been removed from the Patient Demographic Service. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the removal from registration extension.","example":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","enum":["https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration"],"readOnly":true},"extension":{"type":"array","description":"An extension reason a PDS record has been removed from the Patient Demographic Service.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for removalFromRegistrationCode.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"To identify the removal reason code.","example":"removalFromRegistrationCode","enum":["removalFromRegistrationCode"],"readOnly":true},"valueCodeableConcept":{"type":"object","description":"PDS Removal Reason Exit Code","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one removal reason exit code object","items":{"type":"object","required":["system","code","display"],"properties":{"system":{"type":"string","format":"url","description":"URL of the Removal Reason Exit Code. Always uses the 'PDS-RemovalReasonExitCode' Code System.","example":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","readOnly":true},"code":{"type":"string","example":"SCT","enum":["DEA","EMB","SCT","NIT","TRA","ORR"],"description":"A CodeSystem that identifies the reason a PDS record has been removed:\n* `DEA` - Death\n* `EMB` - Embarkation\n* `SCT` - Transferred to Scotland\n* `NIT` - Transferred to Northern Ireland\n* `TRA` - Temporary resident not returned\n* `ORR` - Other reason\n"},"display":{"type":"string","description":"Display-friendly representation of the removal reason exit code.","example":"Transferred to Scotland"}}}}}}}},{"type":"object","description":"Wrapper object for removal from registration effective time.","required":["url","valuePeriod"],"properties":{"url":{"type":"string","description":"Key of this object. Always `effectiveTime`.","example":"effectiveTime","enum":["effectiveTime"],"readOnly":true},"valuePeriod":{"type":"object","description":"The effective time of removal of the Patient record from PDS.","required":["start"],"properties":{"start":{"type":"string","format":"date-time","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2020-01-01T00:00:00+00:00"},"end":{"type":"string","format":"date-time","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2021-12-31T00:00:00+00:00"}}}}}]}}}}]}}}},"example":{"resourceType":"Patient","id":"9000000009","identifier":[{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus","version":"1.0.0","code":"01","display":"Number present and verified"}]}}]}],"meta":{"versionId":"2","security":[{"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality","code":"U","display":"unrestricted"}]},"name":[{"id":"123","use":"usual","period":{"start":"2024-01-01","end":"2025-12-31"},"given":["Jane"],"family":"Smith","prefix":["Mrs"],"suffix":["MBE"]}],"gender":"female","birthDate":"2010-10-22","multipleBirthInteger":1,"deceasedDateTime":"2010-10-22T00:00:00+00:00","generalPractitioner":[{"id":"254406A3","type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345","period":{"start":"2024-01-01","end":"2025-12-31"}}}],"managingOrganization":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345","period":{"start":"2024-01-01","end":"2025-12-31"}}},"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y23456"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y34567"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","extension":[{"url":"deathNotificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus","version":"1.0.0","code":"2","display":"Formal - death notice received from Registrar of Deaths"}]}},{"url":"systemEffectiveDate","valueDateTime":"2010-10-22T00:00:00+00:00"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","extension":[{"url":"language","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage","version":"1.0.0","code":"fr","display":"French"}]}},{"url":"interpreterRequired","valueBoolean":true}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","extension":[{"url":"PreferredWrittenCommunicationFormat","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","code":"12","display":"Braille"}]}},{"url":"PreferredContactMethod","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","code":"1","display":"Letter"}]}},{"url":"PreferredContactTimes","valueString":"Not after 7pm"}]},{"url":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","valueAddress":{"city":"Manchester","district":"Greater Manchester","country":"GBR"}},{"url":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","extension":[{"url":"removalFromRegistrationCode","valueCodeableConcept":{"coding":[{"system":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","code":"SCT","display":"Transferred to Scotland"}]}},{"url":"effectiveTime","valuePeriod":{"start":"2020-01-01T00:00:00+00:00","end":"2021-12-31T00:00:00+00:00"}}]}],"telecom":[{"id":"789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"phone","value":"01632960587","use":"home"},{"id":"790","period":{"start":"2019-01-01","end":"2022-12-31"},"system":"email","value":"jane.smith@example.com","use":"home"},{"id":"OC789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"other","value":"01632960587","use":"home","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem","code":"textphone","display":"Minicom (Textphone)"}}]}],"contact":[{"id":"C123","period":{"start":"2024-01-01","end":"2025-12-31"},"relationship":[{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/v2-0131","code":"C","display":"Emergency Contact"}]}],"telecom":[{"system":"phone","value":"01632960587"}]}],"address":[{"id":"456","period":{"start":"2024-01-01","end":"2025-12-31"},"use":"home","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]},{"id":"T456","period":{"start":"2024-01-01","end":"2025-12-31"},"use":"temp","text":"Student Accommodation","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]}]}}}},"503":{"description":"The request timed out during processing. This does not imply the request has failed or been rejected. Error code: `SERVICE_UNAVAILABLE`.\n\nRe-send the request after the time specified in the `Retry-After` header using the same `X-Request-ID` value.\n","headers":{"RetryAfter":{"description":"Time to wait between polls in seconds","schema":{"type":"string","example":"5"}}},"content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"timeout","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"SERVICE_UNAVAILABLE","display":"Service unavailable"}]},"diagnostics":"The downstream domain processing has not completed within the configured timeout period. Using the same 'X-Request-ID' header, retry your request after the time specified by the 'Retry-After' response header."}]}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | ------------------------------- | --------------------------------------------- |\n| 400 | MISSING_VALUE | Missing header parameter. For details, see the `diagnostics` field. |\n| 400 | INVALID_VALUE | Invalid header parameter or invalid value in body of post request. For details, see the `diagnostics` field. |\n| 400 | VALIDATION_ERROR | This is the \"default\" error thrown when no others are applicable. |\n| 400 | UNSUPPORTED_CHARACTERS_IN_FIELD | Invalid value in body of post request. For details, see the `diagnostics` field. |\n| 400 | ADDITIONAL_PROPERTIES | The user sent additional properties within the dictionary. For example sending a patient post and attempting to include 'pets', which is not an allowed field within the patient resource. |\n| 400 | UNSUPPORTED_VALUE | 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. The invalid value and field will be presented in the display. |\n| 400 | TOO_FEW_VALUES_SUBMITTED | The field in question has a minimum number of items and the user sent too few. |\n| 400 | TOO_MANY_VALUES_SUBMITTED | The field in question has a maximum number of items and the user sent too many. |\n| 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. |\n| 403 | ACCESS_DENIED | Patient cannot perform this action. |\n| 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. |\n| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","headers":{"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"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 - Update unsupported for resource - 'pets'"}]}}}}}}},"/Patient/{id}":{"parameters":[{"name":"id","in":"path","description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","required":true,"schema":{"type":"string","example":"9000000009"}},{"in":"header","name":"Authorization","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\n\nRequired in all environments except sandbox.\n","required":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"in":"header","name":"NHSD-Session-URID","description":"\nThe user role ID (URID) for the current session. Also known as a user role profile ID (URPID).\n\nThis header is optional.\n\nIn Application-restricted and Patient access mode this header is ignored.\n\nIn Healthcare worker access mode if you send this header it must be valid for the logged-in user. See [determine the user's role](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation#step-9-determine-the-user-s-role) for guidance.\n","required":false,"schema":{"type":"string","pattern":"^[0-9]+$","example":"555254240100"}},{"in":"header","name":"X-Request-ID","required":true,"description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\n\nMust be a universally unique identifier (UUID) (ideally version 4).\n\nMirrored back in a response header.\n\nThis is a mandatory header.\n\nIf you re-send a failed request, use the same value in this header.\n","schema":{"type":"string","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"}},{"in":"header","name":"X-Correlation-ID","required":false,"description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\n\nMirrored back in a response header.\n","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"in":"header","name":"NHSD-End-User-Organisation-ODS","required":false,"description":"The ODS code of the user.\n\nMandatory for client applications which service multiple end user organisations (EUO). This will allow the calls to be attributed to the correct EUO.\n","schema":{"type":"string","example":"Y12345"}}],"get":{"description":"## Overview\nUse this endpoint to get patient details from PDS for a given NHS number.\n\nYou cannot get a patient's related people details, use the RelatedPerson endpoint instead.\n\n## Superseded patients\nSome patients are marked as superseded. This means that the original patient details are no longer valid and have been replaced with different details.\n\nOn retrieval of a superseded patient's details, the new details are automatically returned in place of the requested details. You can spot a superseded patient when the `id` is not the same as the one requested.\n\nWhen retrieving superseding patient details you must update your system with the new patient details and remove the superseded patient details, ensuring that the same `id` does not exist against another patient in your system.\n\n## Restricted patients\nSome patients are tagged as [restricted](https://digital.nhs.uk/services/demographics/restricting-access-to-a-patients-demographic-record) and are sometimes known as sensitive patients. Restricted patients can be retrieved; however, location-sensitive fields such as `address`, `telecom` and `generalPractitioner` are removed.\n\nThe restricted flag can be found in the data under `meta/security` on the patient resource.\n\n## Sandbox test scenarios\nYou can test the following scenarios in our sandbox environment:\n\n| Scenario | Request | Response |\n| -------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| Patient exists | `id`=`9000000009` | HTTP Status 200 with patient data in response |\n| Sensitive patient exists | `id`=`9000000025` | HTTP Status 200 with patient data in response with the restricted data removed |\n| 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 |\n| Patient does not exist | `id`=`9111231130` (or any other valid NHS number) | HTTP Status 404 with problem description |\n| Invalid NHS number | `id`=`9000000000` (or any invalid NHS number) | HTTP Status 400 with problem description |\n| Missing X-Request-ID | `id`=`9000000009` (or any other valid NHS number) | HTTP Status 400 with problem description |\n\nYou can try out the sandbox by selecting the 'Try' button at the end of the schema.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n \n \n","summary":"Get patient details","operationId":"get-patient","responses":{"200":{"description":"Information successfully returned.","headers":{"ETag":{"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""},"description":"Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/\"2\"`.\n\nCorresponds to `meta.versionId` attribute in the patient resource body.\n\nWhen 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).\nYou must then pass the resource's version number in any update request (in the `If-Match` response header) made for the patient.\n"},"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"id":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"identifier":{"type":"array","description":"Identifier and system of identification used for this Patient.","maxItems":1,"items":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","description":"System identifier belongs to.","default":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"extension":{"type":"array","description":"FHIR extensions.","items":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}}}}}},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The NHS Digital assigned version of the patient resource.","example":"2"},"security":{"type":"array","description":"The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:\n* U - unrestricted. All available data is returned.\n* R - restricted. Any sensitive data around the patient's location, so `address`, `generalPractitioner` and `telecom`, are removed from the response.\n* REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.\n","maxItems":1,"items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the value set specification.","example":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality"},"code":{"type":"string","description":"Code defined by the system value set.","enum":["U","R","V","REDACTED"],"example":"U"},"display":{"type":"string","description":"Representation defined by the system.","enum":["unrestricted","restricted","redacted"],"example":"unrestricted"}}}}}},"name":{"type":"array","description":"List of names associated with the patient. This may not appear if the patient is tagged as `restricted` (also known as a sensitive patient). \n","minItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"multipleBirthInteger":{"type":"integer","minimum":1,"maximum":9,"description":"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.\n\nThere are two other valid values; `8` meaning `Not applicable` and `9` meaning `Not known`.\n","example":1},"deceasedDateTime":{"description":"The date and time in UTC on which a person died or is officially deemed to have died, if applicable and known.\n\nIt is a datetime in the format `yyyy-mm-ddTHH:MM:SS+00:00` or `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.\n","example":"2010-10-22T00:00:00+00:00","type":"string","format":"date-time","pattern":"^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T\\d{2}:\\d{2}:\\d{2}\\+00:00)$|^([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]))$"},"address":{"type":"array","description":"List of addresses associated with the patient.\n\nThese are fully populated on a retrieval or a successful update, only the `home` address is returned on a search.\nWhen a patient tagged as `restricted` is retrieved, all addresses are removed from the response.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient, like phone numbers or email addresses. A patient should only have one instance of each telecom system and use combination on their record at a time. For example, to add a new work email value to the record, the existing work email value should be replaced with the new value. When a patient tagged as `restricted` is retrieved, all contact points, like phone numbers or email addresses, are removed from the response.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"contact":{"type":"array","description":"A list of patient contacts. Only emergency contacts are returned and only emergency contacts should be added. Any other contacts should be added to the patients `Related Person`.\nPatients designate here any contact number they desire to be used in case of an emergency.\nNote, 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.\nWhen a patient tagged as `restricted` is retrieved, all contacts are removed from the response.\n","items":{"title":"Schema for a patient contact.","type":"object","additionalProperties":false,"required":["relationship","telecom"],"properties":{"id":{"type":"string","example":"C123"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"relationship":{"type":"array","description":"The contact relationship wrapper object that holds the details of the relationship to the patient.\n\nThis is only returned when an Emergency Contact number has been set on `telecom`. The only valid code is `C`, which means `Emergency Contact`.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}}},"telecom":{"type":"array","description":"List of Telecom objects on the contact only contains `system` and `value`.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}}}}},"generalPractitioner":{"type":"array","maxItems":1,"description":"General Practice (not practitioner) with which the patient is, or was, registered. Always contains zero or one general practitioner object.\nWhen a patient tagged as `restricted` is retrieved, the General Practice is removed from the response.\n","items":{"description":"General practice (not practitioner) with which the patient is or was registered.","type":"object","required":["identifier"],"properties":{"id":{"description":"Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.","type":"string","example":"254406A3"},"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}}},"managingOrganization":{"description":"The managing organization of a de-registered patient. This will not be returned when the reason for de-registration is death.","type":"object","required":["identifier"],"properties":{"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}},"extension":{"type":"array","description":"Wrapper array for the patient's pharmacies, death notification status, communication details, contact preferences and place of birth; these are all FHIR extensions.\nAlways 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.\nWhen a patient tagged as `restricted` is retrieved, the pharmacy and birth place extensions are removed from the response.\n","items":{"anyOf":[{"type":"object","description":"Wrapper object for the patient's nominated pharmacy. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-NominatedPharmacy FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy"]},"valueReference":{"type":"object","description":"Reference to a pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's nominated pharmacy organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the nominated pharmacy, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y12345"}}}}}}},{"type":"object","description":"Wrapper object for the patient's dispensing doctor. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-DispensingDoctor FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization"]},"valueReference":{"type":"object","description":"Reference to a GP practice pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's dispensing doctor organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the dispensing doctor, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y23456"}}}}}}},{"type":"object","description":"Wrapper object for the patient's medical appliance supplier. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-MedicalApplianceSupplier FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier"]},"valueReference":{"type":"object","description":"Reference to medical appliance supplier pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's medical appliance supplier organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the medical appliance supplier, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y34567"}}}}}}},{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for place of birth details. This will not be returned on a restricted patient.","required":["url","valueAddress"],"properties":{"url":{"type":"string","description":"Definition of place of birth extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","enum":["http://hl7.org/fhir/StructureDefinition/patient-birthPlace"]},"valueAddress":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string","description":"Town or city of birth.","example":"Manchester"},"district":{"type":"string","description":"County or metropolitan district of birth.","example":"Greater Manchester"},"country":{"type":"string","description":"A coded value for a patient's country of birth.\n\nFrom [ISO 3166-1](http://hl7.org/fhir/valueset-iso3166-1-3.html) plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.\n\nUK Internal Codes:\n* `1` - England\n* `2` - Scotland\n* `3` - Wales\n* `4` - Northern Ireland\n* `7` - Sark\n* `9` - Alderney\n* `10` - Channel Islands\n","example":"GBR"}}}}},{"type":"object","description":"An extension to carry the reason a PDS record has been removed from the Patient Demographic Service. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the removal from registration extension.","example":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","enum":["https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration"],"readOnly":true},"extension":{"type":"array","description":"An extension reason a PDS record has been removed from the Patient Demographic Service.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for removalFromRegistrationCode.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"To identify the removal reason code.","example":"removalFromRegistrationCode","enum":["removalFromRegistrationCode"],"readOnly":true},"valueCodeableConcept":{"type":"object","description":"PDS Removal Reason Exit Code","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one removal reason exit code object","items":{"type":"object","required":["system","code","display"],"properties":{"system":{"type":"string","format":"url","description":"URL of the Removal Reason Exit Code. Always uses the 'PDS-RemovalReasonExitCode' Code System.","example":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","readOnly":true},"code":{"type":"string","example":"SCT","enum":["DEA","EMB","SCT","NIT","TRA","ORR"],"description":"A CodeSystem that identifies the reason a PDS record has been removed:\n* `DEA` - Death\n* `EMB` - Embarkation\n* `SCT` - Transferred to Scotland\n* `NIT` - Transferred to Northern Ireland\n* `TRA` - Temporary resident not returned\n* `ORR` - Other reason\n"},"display":{"type":"string","description":"Display-friendly representation of the removal reason exit code.","example":"Transferred to Scotland"}}}}}}}},{"type":"object","description":"Wrapper object for removal from registration effective time.","required":["url","valuePeriod"],"properties":{"url":{"type":"string","description":"Key of this object. Always `effectiveTime`.","example":"effectiveTime","enum":["effectiveTime"],"readOnly":true},"valuePeriod":{"type":"object","description":"The effective time of removal of the Patient record from PDS.","required":["start"],"properties":{"start":{"type":"string","format":"date-time","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2020-01-01T00:00:00+00:00"},"end":{"type":"string","format":"date-time","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2021-12-31T00:00:00+00:00"}}}}}]}}}}]}}}},"example":{"resourceType":"Patient","id":"9000000009","identifier":[{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus","version":"1.0.0","code":"01","display":"Number present and verified"}]}}]}],"meta":{"versionId":"2","security":[{"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality","code":"U","display":"unrestricted"}]},"name":[{"id":"123","use":"usual","period":{"start":"2024-01-01","end":"2025-12-31"},"given":["Jane"],"family":"Smith","prefix":["Mrs"],"suffix":["MBE"]}],"gender":"female","birthDate":"2010-10-22","multipleBirthInteger":1,"deceasedDateTime":"2010-10-22T00:00:00+00:00","generalPractitioner":[{"id":"254406A3","type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345","period":{"start":"2024-01-01","end":"2025-12-31"}}}],"managingOrganization":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345","period":{"start":"2024-01-01","end":"2025-12-31"}}},"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y23456"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y34567"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","extension":[{"url":"deathNotificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus","version":"1.0.0","code":"2","display":"Formal - death notice received from Registrar of Deaths"}]}},{"url":"systemEffectiveDate","valueDateTime":"2010-10-22T00:00:00+00:00"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","extension":[{"url":"language","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage","version":"1.0.0","code":"fr","display":"French"}]}},{"url":"interpreterRequired","valueBoolean":true}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","extension":[{"url":"PreferredWrittenCommunicationFormat","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","code":"12","display":"Braille"}]}},{"url":"PreferredContactMethod","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","code":"1","display":"Letter"}]}},{"url":"PreferredContactTimes","valueString":"Not after 7pm"}]},{"url":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","valueAddress":{"city":"Manchester","district":"Greater Manchester","country":"GBR"}},{"url":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","extension":[{"url":"removalFromRegistrationCode","valueCodeableConcept":{"coding":[{"system":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","code":"SCT","display":"Transferred to Scotland"}]}},{"url":"effectiveTime","valuePeriod":{"start":"2020-01-01T00:00:00+00:00","end":"2021-12-31T00:00:00+00:00"}}]}],"telecom":[{"id":"789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"phone","value":"01632960587","use":"home"},{"id":"790","period":{"start":"2019-01-01","end":"2022-12-31"},"system":"email","value":"jane.smith@example.com","use":"home"},{"id":"OC789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"other","value":"01632960587","use":"home","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem","code":"textphone","display":"Minicom (Textphone)"}}]}],"contact":[{"id":"C123","period":{"start":"2024-01-01","end":"2025-12-31"},"relationship":[{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/v2-0131","code":"C","display":"Emergency Contact"}]}],"telecom":[{"system":"phone","value":"01632960587"}]}],"address":[{"id":"456","period":{"start":"2024-01-01","end":"2025-12-31"},"use":"home","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]},{"id":"T456","period":{"start":"2024-01-01","end":"2025-12-31"},"use":"temp","text":"Student Accommodation","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]}]}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | --------------------------------------------- |\n| 400 | INVALID_RESOURCE_ID | Invalid NHS number. |\n| 400 | UNSUPPORTED_SERVICE | Missing NHS number. |\n| 400 | MISSING_VALUE | Missing header parameter. For details, see the `diagnostics` field. |\n| 400 | INVALID_VALUE | Invalid header parameter. For details, see the `diagnostics` field. |\n| 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. |\n| 403 | ACCESS_DENIED | Patient cannot perform this action. |\n| 404 | RESOURCE_NOT_FOUND | Patient does not exist for given NHS number. |\n| 404 | INVALIDATED_RESOURCE | Patient did exist for given NHS number, but has been invalidated and not superseded by another NHS number. |\n| 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. |\n| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"structure","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"MISSING_VALUE","display":"Required value is missing"}]},"diagnostics":"Missing value - 'birth_date/birth_date_range_start/birth_date_range_end'"}]}}}}}},"patch":{"description":"## Overview\nUse this endpoint to update patient details in PDS.\n\nThis 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.\n\nWhen you make a PATCH request with your application, the endpoint will respond with a successful (200) response code, along with the updated patient resource, or, an unsuccessful (4xx/5xx) response. \n\n99.99% of all updates complete in under 10 seconds. If an update takes longer than 10 seconds, the endpoint responds with an HTTP status of 503 (Gateway Timeout). \n\nYou can alter the timeout period using the `X-Sync-Wait` header. If you re-submit the update, use the same `X-Request-ID` header.\n\nThe behaviour of this endpoint depends on which access mode you are using:\n\n| Access mode | Behaviour restrictions |\n| ------------------------------ | ----------------------------------- |\n| Application-restricted access | Updates not allowed |\n| Healthcare worker access | Updates allowed |\n| Patient access | Updates allowed (limited) |\n\n## Patient resource versioning\nTo update a patient's resource you must have retrieved it first, to ensure you are working against an up-to-date patient resource.\n\nWhen 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\"`).\n\nYou must then pass the patient's version number in the update request (in the `If-Match` response header).\n\nIt 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.\n\nThe update only succeeds, if the patient resource has not been updated in our database between your first retrieval and the update request.\n\nIf the update succeeds, you will receive the updated patient resource, this will contain the new resource version number.\n\nIf you make a subsequent update you must use the new version number.\n\n## JSON Patch\nTo update a patient record, a [JSON Patch](https://tools.ietf.org/html/rfc6902) should be sent. A JSON Patch consists of one or more patch objects within a list.\n\nIt is recommended that all desired updates are sent together in a single request as a list of patches.\nThis is the most efficient approach and reduces the danger of race conditions occurring when updating the patient record multiple times in a short period of time.\n\nWhen 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 are applied.\n\nA patch object consists of:\n* an operation, `op` - this is required.\n* a path to the data that you want to change, `path` - this is required.\n* the value that is assigned, `value` - this is required for `add`, `replace` and `test`; but should not be included for a `remove`.\n\nThe following operations are supported:\n* `add` - to add a new value.\n* `replace` - to replace an existing value.\n* `remove` - to remove an existing value.\n* `test` - to test the state of a value is as expected before continuing with the update.\n\nPaths point to a single value, list or object, for example:\n* `/gender` - pointing to the gender value.\n* `/name` - point to the name list.\n* `/name/0` - pointing to the 1st object in the name list.\n* `/address/0/line/1` - pointing to the 2nd line string in the 1st address object.\n\nThe value can be set to any valid value for that path, so could be a null, a string, an object or a list.\n\n### Addition\n\n`add` should be used to add new items to a patient.\n\nAdding a simple data item such as the date of death can be done using a patch such as:\n\n```json\n{\n \"patches\": [\n { \"op\": \"add\", \"path\": \"/deceasedDateTime\", \"value\": \"2020-01-01\" }\n ]\n}\n```\n\nAdding 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, the index is not known:\n\n```json\n{\n \"patches\": [\n {\n \"op\": \"add\",\n \"path\": \"/name/-\",\n \"value\": {\n \"use\": \"usual\",\n \"period\": { \"start\": \"2024-12-31\" },\n \"prefix\": [\"Dr\"],\n \"given\": [\n \"Joe\",\n \"Horation\",\n \"Maximus\"\n ],\n \"family\": \"Bloggs\",\n \"suffix\": [\"PhD\"]\n }\n }\n ]\n}\n```\n\nWhen adding a base level list item such as a new name or address, ensure the index is always `-`, otherwise the request is rejected. For example, `/name/-`.\nThe reason for this is because the backend system makes the decision on the ordering of the listed objects to ensure they are always returned in the same order.\n\nIf you are adding to a sub-element that is a list, such as an extra given name, it is valid to provide an exact index. So the following is valid:\n\n```json\n{\n \"patches\": [\n {\n \"op\": \"add\", \"path\": \"/name/0/id\", \"value\": \"8F8B957D\"\n },\n {\n \"op\": \"add\", \"path\": \"/name/0/given/0\", \"value\": \"Rose\"\n }\n ]\n}\n```\n\nIt 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 is rejected.\nThe following patch is allowed:\n\n```json\n{\n \"patches\": [\n {\n \"op\": \"add\", \"path\": \"/name/0/id\", \"value\": \"8F8B957D\"\n },\n {\n \"op\": \"add\", \"path\": \"/name/0/given/0\", \"value\": \"Rose\"\n }\n ]\n}\n```\n\nbut the following is not allowed:\n\n```json\n{\n \"patches\": [\n {\n \"op\": \"add\", \"path\": \"/name/0/given/-\", \"value\": \"Rose\"\n }\n ]\n}\n```\n\n### Replacing\n\n`replace` should be used to alter existing items on the patient.\n\nReplacing a simple data item such as the gender can be done using a patch such as:\n\n```json\n{\n \"patches\": [\n { \"op\": \"replace\", \"path\": \"/gender\", \"value\": \"male\" }\n ]\n}\n```\n\nReplacing 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.\n\nThe first approach is to replace the whole list item:\n\n```json\n{\n \"patches\": [\n {\n \"op\": \"replace\",\n \"path\": \"/name/0\",\n \"value\": {\n \"id\": \"123\",\n \"use\": \"usual\",\n \"period\": { \"start\": \"2024-12-31\" },\n \"prefix\": [\"Dr\"],\n \"given\": [\n \"Joe\",\n \"Horation\",\n \"Maximus\"\n ],\n \"family\": \"Bloggs\",\n \"suffix\": [\"PhD\"]\n }\n }\n ]\n}\n```\n\nThe second approach is to replace just a part, or parts, of the list object keys if all others remain the same:\n\n```json\n{\n \"patches\": [\n { \"op\": \"replace\", \"path\": \"/name/0/id\", \"value\": \"123\" },\n { \"op\": \"replace\", \"path\": \"/name/0/prefix/0\", \"value\": \"Mr\" },\n { \"op\": \"replace\", \"path\": \"/name/0/family\", \"value\": \"Smith\" }\n ]\n}\n```\n\nAn 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 is in the object on retrieval so just needs to be mirrored back. You should not include an ID on an addition as this is automatically generated by the system and is a unique object ID, so only our system can guarantee that.\n\n### Removal\n\n`remove` should be used to delete existing items on a patient.\n\nRemoving a simple data item such as the gender can be done using a patch such as:\n\n```json\n{\n \"patches\": [\n { \"op\": \"remove\", \"path\": \"/gender\" }\n ]\n}\n```\n\nNote, that in this scenario, although the patch is perfectly valid, the update is still rejected as a patients gender cannot be removed.\n\nRemoving a list item should only be done on the whole item object, not individual sub-items; instead use the replace operation.\n\nTo remove a list item, a `test` operation must immediately precede 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:\n\n* the `id` - the object ID for items that have one - for example `name`, `address` or `telecom`\n* the `url` - the URL for the extension being removed\n* the whole object being removed\n\nAn example of a list item removal using the `id` would be:\n\n```json\n{\n \"patches\": [\n { \"op\": \"test\", \"path\": \"/name/0/id\", \"value\": \"123\" },\n { \"op\": \"remove\", \"path\": \"/name/0\" }\n ]\n}\n```\n\nAn example of a extension list item removal using the `url` would be:\n\n```json\n{\n \"patches\": [\n { \"op\": \"test\", \"path\": \"/extension/0/url\", \"value\": \"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus\" },\n { \"op\": \"remove\", \"path\": \"/extension/0\" }\n ]\n}\n```\n\nAn example of a list item removal using the whole object would be:\n\n```json\n{\n \"patches\": [\n { \n \"op\": \"test\",\n \"path\": \"/name/0\",\n \"value\": {\n \"id\": \"123\",\n \"use\": \"usual\",\n \"period\": { \"start\": \"2024-12-31\" },\n \"prefix\": [\"Dr\"],\n \"given\": [\n \"Joe\",\n \"Horation\",\n \"Maximus\"\n ],\n \"family\": \"Bloggs\",\n \"suffix\": [\"PhD\"]\n }\n },\n { \"op\": \"remove\", \"path\": \"/name/0\" }\n ]\n}\n```\n### Special considerations for removals ###\n\nSee the [Patient access section](#patient-access) for information on updating fields in Patient access mode. \n\nYou should take special care when performing multiple removals in the same list. Removing a particular index could affect all subsequent index positions. We recommend sorting those snippets in descending order of their index. For example, for removing multiple \"family\" values from index 1, 2 and 4 from the \"name\" snippet, you should test and remove them from the highest to lowest, from 4 to 2 to 1. This will prevent update failures caused by values re-indexing after each update.\n\nThe next two examples perform **exactly** the same operation.\n\nUsing the following initial (simplified) data, with the intention of removing the names in index 1 (Irwin) and 2 (Bruce):\n\n```json\n{\n \"name\": [\n {\"id\": \"2\", \"family\": \"Parker\"},\n {\"id\": \"3\", \"family\": \"Irwin\"},\n {\"id\": \"4\", \"family\": \"Bruce\"},\n {\"id\": \"5\", \"family\": \"Sharpe\"}\n ]\n}\n```\n\n**Example 1**:\n\n```json\n{\n \"patches\": [\n { \"op\": \"test\", \"path\": \"/name/1/id\", \"value\": \"3\" },\n { \"op\": \"remove\", \"path\": \"/name/1\" },\n { \"op\": \"test\", \"path\": \"/name/1/id\", \"value\": \"4\" },\n { \"op\": \"remove\", \"path\": \"/name/1\" }\n ]\n}\n```\n\nAfter the 1st removal the data looks like:\n\n```json\n{\n \"name\": [\n {\"id\": \"2\", \"family\": \"Parker\"},\n {\"id\": \"4\", \"family\": \"Bruce\"},\n {\"id\": \"5\", \"family\": \"Sharpe\"}\n ]\n}\n```\n\nmeaning Irwin has been removed, Bruce has moved from index 2 -> 1 and Sharpe from 3 -> 2.\n\nSo after applying the 2nd removal the data looks like:\n\n```json\n{\n \"name\": [\n {\"id\": \"2\", \"family\": \"Parker\"},\n {\"id\": \"5\", \"family\": \"Sharpe\"}\n ]\n}\n```\n\nWhich 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.\n\n**Example 2**:\n\n```json\n{\n \"patches\": [\n { \"op\": \"test\", \"path\": \"/name/2/id\", \"value\": \"4\" },\n { \"op\": \"remove\", \"path\": \"/name/2\" },\n { \"op\": \"test\", \"path\": \"/name/1/id\", \"value\": \"3\" },\n { \"op\": \"remove\", \"path\": \"/name/1\" }\n ]\n}\n```\n\nAfter the 1st removal the data looks like:\n\n```json\n{\n \"name\": [\n {\"id\": \"2\", \"family\": \"Parker\"},\n {\"id\": \"3\", \"family\": \"Irwin\"},\n {\"id\": \"5\", \"family\": \"Sharpe\"}\n ]\n}\n```\n\nApplying the 2nd removal the data looks like:\n\n```json\n{\n \"name\": [\n {\"id\": \"2\", \"family\": \"Parker\"},\n {\"id\": \"5\", \"family\": \"Sharpe\"}\n ]\n}\n```\n\nWhich 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.\n\n**Example 3 - a failure**\n\n```json\n{\n \"patches\": [\n { \"op\": \"test\", \"path\": \"/name/1/id\", \"value\": \"3\" },\n { \"op\": \"remove\", \"path\": \"/name/1\" },\n { \"op\": \"test\", \"path\": \"/name/2/id\", \"value\": \"4\" },\n { \"op\": \"remove\", \"path\": \"/name/2\" }\n ]\n}\n```\n\nAfter the 1st removal the data looks like:\n\n```json\n{\n \"name\": [\n {\"id\": \"2\", \"family\": \"Parker\"},\n {\"id\": \"4\", \"family\": \"Bruce\"},\n {\"id\": \"5\", \"family\": \"Sharpe\"}\n ]\n}\n```\n\nWhen applying the 2nd test, it fails as the index 2 ID is `5`, but the test was looking for `4`. An error is returned and none of the updates provided would be made to the database.\n\nThis 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:\n\n```json\n{\n \"name\": [\n {\"id\": \"2\", \"family\": \"Parker\"},\n {\"id\": \"4\", \"family\": \"Bruce\"}\n ]\n}\n```\n\nWhich is incorrect, as Irwin and Sharpe were removed instead of Irwin and Bruce.\n\n### Business rules for period\n\nExcept where stated in the data fields, these rules apply for the `period` object:\n* a `period` object is optional\n* when adding a new value or replacing a whole object, if a period is not provided, today's date will be applied as the `start` date.\n* when replacing a specific value (for example, the second line of the address only) the original period.start date is kept.\n* if a `period` object is supplied, a `start` date must also be provided.\n* a `start` date must not be in the future.\n* an `end` date must not be before the `start` date.\n\n\n## Patient data fields\n\n### Address\n\nList item found under `address` field.\n\nIn a JSON Patch request the path should be:\n* `/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 is `/address/1`, and so on.\n* `/address/-` when adding a new address.\n\nAn address consists of 5 lines of unstructured text, postcode, and address keys. Address keys can include a PAF or a UPRN.\n\nPostcode is optional but strongly encouraged.\nIf the address has no postcode, use a [pseudo postcode from the list defined by the Office for National Statistics](https://digital.nhs.uk/services/organisation-data-service/data-search-and-export/csv-downloads/office-for-national-statistics-data) (see the 'look_ups' file).\n\nIn particular, for a patient at no fixed abode, use the pseudo postcode `ZZ99 3VZ`.\n\nWe recommend you use the [OS Places API](https://digital.nhs.uk/developer/api-catalogue/ordnance-survey-places-api) for looking up and verifying addresses prior to a PDS update. \n\nWhen adding or replacing address lines, use the following rules:\n* line 1 - premises ID and/or house name, for example `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, for example `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), for example `Boxgrove`\n* line 4 - post town, for example `Leeds`\n* line 5 - county (if present), for example `West Yorkshire`\n\nWhen updating an address, you should populate lines 1 or 2, and line 4. You should not include line 5 in manually created addresses but you may include it in PAF-derived addresses. The address ID must also be included in the update as shown in the below examples.\n\nThere are exceptions:\n* if you submit a postcode and PAF key, in which case the lines are automatically populated, however if there are no matches or too many matches the message is rejected due to missing address lines\n* if you use a pseudo postcode, for example `ZZ99 3VZ` meaning `no fixed abode`\n\nWhen creating the FHIR payload message, to be fully FHIR compliant all empty lines should be removed, so for example:\n\n```json\n{\n \"address\": {\n \"line\": [\n \"\",\n \"23 Mill Lane\",\n \"\",\n \"Leeds\",\n \"\"\n ]\n }\n\n}\n```\n\nshould be sent in as:\n\n```json\n {\n \"address\": {\n \"line\": [\n \"23 Mill Lane\",\n \"Leeds\"\n ]\n }\n\n }\n```\n\nhowever if you do not do this the message is not rejected; the response is in that form though.\n\nTo ensure consistent data across all patient addresses, you should match addresses to the PAF and send them in PAF format including the PAF key.\nIf you do not include the PAF key it is added to the address if a match is found\nAdditionally the provided address lines and post code are enriched and reformatted if necessary.\n\nThe following address types are supported:\n* `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n* `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n* `billing` - an address used for correspondence purposes only\n\nA patient must have no more than one current `temp` and/or `billing` address.\nHowever, 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.\nWhere 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 (for example by examining period dates).\n\nA `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:\n* 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.\n* 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.\n\nNot 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.\nWhen the end date for a `temp` or `billing` address passes, local systems should use the patient’s `home` address. It is extremely rare that no `home` address is present on a patient record.\n\nBe aware of the following business rules:\n* you cannot add more than one of each address use types; `home`, `temp` or `billing`\n* `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\n* any `temp` address must have both a `period start` and a `period end` date. The end date is required so that consumers know when to remove data that is no longer relevant to the patient. A suggested default where no actual period end is known is 30 days later than the period start, up to a maximum of 90 days.\n* period object is mandatory when adding or replacing a temporary or billing address. The provided period object must contain a start and end date.\n* any `billing` address must have both a `period start` and a `period end` date. The end date is required so that consumers know when to remove data that is no longer relevant to the patient. A suggested default where no actual period end is known is 30 days later than the period start, up to a maximum of 366 days.\n* where a `temp` address is provided a description must be sent using the `text` field, the list of allowed values are:\n * `Second Home` - a patient's second home\n * `Student Accommodation` - a patient's place of residence while at university\n * `Respite Care Address` - where the patient resides during respite care\n * `Temporary Residence Address` - where the patient resides for a specific period of time\n * `Convalescence Home` - the address for a patient during a period of recovery\n * `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\n * `Holiday Home` - the address for a patient during a holiday\n In rare circumstances, an existing temporary address may be returned with a value outside of this list.\n\nFor more information on how this data is used, see [Get and update contact details in PDS](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/get-and-update-contact-details-in-pds#address-information)\n\n### Communication\n\nSingle item found under `extension` with the extension URL `https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication`.\n\nIn a JSON Patch request, where the communication extension does not exist the path should be:\n* `/extension/-` when adding a communication extension.\n\nWhere you are replacing/removing the full communication extension, the path should be:\n* `/extension/0` if the communication extension is the first item in the list. If it is the second item in the list the path is `/extension/1`, and so on.\n\nWhere the communication extension already exists and you wish to replace a specific sub-extension, then the path should be:\n* `/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.\n\nYou can find examples of the above requests in our sandbox Postman collection\n\nThere are a number of business rules that should be taken into account:\n* preferred language must not be supplied where it is English even though the [code list](https://simplifier.net/resolve?target=simplifier&scope=uk.nhsdigital.r4&canonical=https://fhir.hl7.org.uk/ValueSet/UKCore-HumanLanguage) contains a value for English (en).\n* any language codes outside the accepted list are rejected; such as local system `qa` codes.\n\n### Contact preferences\nSingle item found under `extension` with the extension URL `https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference`.\n\nIn a JSON Patch request, where the Contact Preference extension does not exist or you are replacing/removing the full list of Contact preferences, the path should be:\n* `/extension/0` if the contact preference is the first item in the list. If it is the second item in the list the path is `/extension/1`, and so on.\n* `/extension/-` when adding a contact preference.\n\nWhere 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:\n* `/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.\n\nYou can find examples of the above requests in our sandbox Postman collection \n\nThere are a number of business rules that should be taken into account:\n* a patient can have `0` or `1` contact preference.\n* preferred contact time is a free-text field limited to 40 characters.\n* where a contact time is specified a contact method must also exist.\n\n### Date of birth\n\nSingle item found under `birthDate` field.\n\nIn a JSON Patch request the path should be `/birthDate`.\n\nWhen adding or updating the birth date, the update should be in the format `yyyy-mm-dd`.\n\nThere are a number of business rules that should be taken into account:\n* cannot be removed.\n* cannot be a date in the future.\n* cannot be after the deceased date, if present.\n\n### Date of death\n\nSingle item found under `deceasedDateTime` field.\n\nIn a JSON Patch request the path should be `/deceasedDateTime`.\n\nWhen adding or updating the deceased date time, the time should be UTC and formatted as `yyyy-mm-ddTHH:MM:SS+00:00`, with a zero UTC offset.\n\nThere are a number of business rules that should be taken into account:\n* cannot be removed.\n* cannot be a date in the future.\n* cannot be before the birth date.\n* cannot be replaced if the death notification status is 2 (formal).\n* when adding date of death, a death notification status must also be added.\n\n### Death notification\n\nSingle item found under `extension` with the extension URL `https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus`.\n\nIn a JSON Patch request the path should be:\n* `/extension/0` if the death notification is the first item in the list. If it is the second item in the list the path is `/extension/1`, and so on.\n* `/extension/-` when adding a death notification.\n\nYou can find examples of the above requests in our sandbox Postman collection\n\nThere are a number of business rules that should be taken into account:\n* cannot be removed.\n* cannot be replaced if the death notification status is formal (2).\n* only certain endpoints can set a death notification of formal (2).\n* when adding a death notification, a deceased date time must also be added.\n\n### Emergency contact\n\nList item found under `contact` field.\n\nIn a JSON Patch request the path should be:\n* `/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 is `/contact/1`, and so on.\n* `/contact/-` when adding a new contact.\n\nOnly emergency contact details should be added to `contact`, regular telecommunication methods such as home phone should be added to the `telecom` field.\nAny other contact relationship types are rejected.\n\nThere are a number of business rules that should be taken into account:\n* in any telecom child object the `use` key should not be present.\n* in any telecom child object the system cannot be `fax`.\n* the date period is optional; where present they must be valid dates and the `end` date cannot be before the `start` date.\n* the date period, if present, should be on the parent `contact` object and not any `telecom` child objects.\n* if the system is email, the value must be a valid email format, for example john.smith@example.com; and must be more than 6 characters and less than 90 characters\n* the relationship can only be `C` meaning `Emergency Contact`\n\n### Gender\n\nSingle item found under `gender` field.\n\nIn a JSON Patch request the path should be `/gender`.\n\nWhen setting a gender, the local system should encourage the user to select `male` or `female` rather than `unknown`.\nThe 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.\n\nThere are a number of business rules that should be taken into account:\n * cannot be removed.\n * can only be `male`, `female` or `unknown`.\n * cannot set gender to `other`.\n\n### General practice\n\nList item found under `generalPractitioner` field. Although only a single general practice is allowed.\n\nIn a JSON Patch request the path should be:\n* `/generalPractitioner/0` for replacing or removing the general practice.\n* `/generalPractitioner/-` when adding a new general practice.\n\nThere are a number of business rules that should be taken into account:\n* only valid GP Practice codes may be used, see [Organisation Data Service FHIR API](https://developer.nhs.uk/apis/ods/) for more details on valid codes.\n* do not provide a period `end` date.\n* the general practice should only be updated by primary care systems, [NHAIS](https://digital.nhs.uk/services/nhais) or by the National Back Office.\n* removal of a general practice can only be done by [NHAIS](https://digital.nhs.uk/services/nhais) or by the National Back Office.\n* only a single general practice is supported; emergency, temporary and additional practices must be maintained in the local system only.\n\n### Managing Organisation (internal-use only)\n\nSingle item found under `managingOrganization` field.\n\nIn a JSON Patch request the path should be `/managingOrganization`.\n\nThe following business rules should be observed:\n* only valid GP Practice codes may be used, see [Organisation Data Service FHIR API](https://developer.nhs.uk/apis/ods/) for more details on valid codes.\n* only a single general practice is supported; emergency, temporary and additional practices must be maintained in the local system only.\n\n### Multiple birth order\n\nSingle item found under `multipleBirthInteger` field.\n\nIn a JSON Patch request the path should be `/multipleBirthInteger`.\n\nWhen adding or updating the birth order, the update should be an integer in the range `1` - `9` inclusive. These values have differing meanings:\n* 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.\n* 8 - `Not applicable`\n* 9 - `Not known`\n\n### Name\n\nList item found under `name` field.\n\nIn a JSON Patch request the path should be:\n* `/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 is `/name/1`, and so on.\n* `/name/-` when adding a new name.\n\nThere are a number of business rules that should be taken into account:\n* cannot add more than one `usual` name.\n* cannot remove the `usual` name.\n* cannot add more than one `nickname`.\n* can have multiple instances of all other name use types.\n* 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.\n* the first character of each `suffix` item must be `A-Z`.\n* supplied name data can only contain characters from the following ranges:\n\n| Character Code/Range | Examples |\n|----------------------|---------------|\n| 65-90 | A-Z |\n| 97-122 | a-z |\n| 45 | Apostrophe |\n| 39 | Hyphen |\n| 32 | Space |\n| 192-214 | À, Æ, Ö, ... |\n| 216-246 | Ø, ß, ö, ... |\n| 248-383 | ø, ü, ÿ, ... |\n| 46 | Full-stop |\n| 48-57\t | Numbers |\n\n* 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:\n * Mr\n * Mrs\n * Ms\n * Dr\n * Rev\n * Sir\n * Lady\n * Lord\n* any trailing full stops at the end of a prefix are automatically removed; for example `Mrs.` changes to `Mrs`.\n\n### Pharmacy\n\nSingle item found under `extension` with one of the extension urls:\n* `https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy`\n* `https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier`\n* `https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization`\n\nIn a JSON Patch request the path should be:\n* `/extension/0` if the pharmacy is the first item in the list. If it is the second item in the list the path is `/extension/1`, and so on\n* `/extension/-` when adding a pharmacy\n\nThere are a number of business rules that should be taken into account:\n* multiple pharmacies are allowed, however only one of each type\n* there are no effective date periods, only a single current instance of each type is supported\n* only valid National Pharmacy codes may be used for the pharmacy identifier, see [Organisation Data Service FHIR API](https://developer.nhs.uk/apis/ods/) for more details on valid codes\n\n### Place of birth\n\nSingle item found under `extension` with the extension URL `http://hl7.org/fhir/StructureDefinition/patient-birthPlace`.\n\nIn a JSON Patch request the path should be:\n* `/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 is `/extension/1`, and so on\n* `/extension/-` when adding a place of birth\n\nThere are a number of business rules that should be taken into account:\n* the three fields, `city`, `district` and `country` are all optional, however at least one of them must be provided\n* country is a coded value and must be in the set of valid values\n\n### Telecom\n\nList item found under `telecom` field.\n\nIn a JSON Patch request the path should be:\n* `/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 is `/telecom/1`, and so on\n* `/telecom/-` when adding a new telecom\n\nIn PDS, a telecom is made up of two values: a 'system' and a 'use'. The telecom system values are:\n* phone\n* fax\n* email\n* other\n\nThe telecom use values are:\n* home\n* work\n* temp\n* mobile\n\nA patient should only have one instance of each telecom value on their record at a time. For example, to add a new work email value to the record, the existing work email value should be replaced with the new value.\n\nEmergency contact details should not be added to the `telecom` field, instead they should be added to the `contact` field.\n\nThere are a number of business rules that should be taken into account:\n* the date period is optional; where present they must be valid dates and the `end` date cannot be before the `start` date\n* the period `start` date is optional, however if provided cannot be a future date. If it is not provided it defaults to the date of update.\n* if using the `replace` operation, the use and system must be the same as the telecom you're modifying. Otherwise use a delete and add instead.\n* if the telecom system is email, the value must be a valid email format, for example john.smith@example.com; and must be more than 6 characters and less than 90 characters\n\nFor more information on how this data is used, see [Get and update contact details in PDS](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir/get-and-update-contact-details-in-pds#telecom-information)\n\n## Access Mode\n\n### Healthcare worker access\n\nA user with Healthcare worker access will be able to update the following fields:\n* Address\n* Communication\n* Contact preferences\n* Date of birth\n* Date of death\n* Death notification\n* Emergency contact\n* Gender\n* General practice\n* Managing Organisation (internal use only)\n* Multiple birth order\n* Name\n* Pharmacy\n* Place of birth\n* Telecom\n\n### Patient access\n\nA user with Patient access will be able to update the following fields:\n* Address\n* Communication (communication language and interpreter required only)\n* Emergency contact\n* Pharmacy\n* Place of birth\n* Telecom (mobile and email only)\n\nIn Patient access mode, for all operations except `remove`, you must include the whole object in the patch to update the following fields: \n* Communication (communication language and interpreter required only)\n* Pharmacy\n* Place of birth\n* Telecom (mobile and email only) \n\n## Sandbox test scenarios\n\nYou can test the following scenarios in our sandbox environment.\n\nThings to note when using the sandbox for PATCH:\n* Your changes are not persisted.\n* JSON Patch operations themselves are validated, but the resulting resource is not validated for correctness; meaning any business rules are not applied.\n* 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).\n\n| Scenario | Request | Response |\n| ----------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ |\n| 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 200 with updated patient resource. |\n| Patient does not exist | `id`=`9111231130` (or any other valid NHS number) | HTTP Status 404 with problem description |\n| Invalid NHS number | `id`=`9000000000` (or any invalid NHS number) | HTTP Status 400 with problem description |\n| Missing resource version identifier | `If-Match` header missing or set to format other than `W/\"\"` | HTTP Status 412 with problem description |\n| Incorrect resource version | `If-Match`=`W/\"1\"` | HTTP Status 409 with problem description |\n| Wrong content type | `Content-Type` header missing or other than `application/json-patch+json` | HTTP Status 400 with problem description |\n| No patches sent | Send body with no `patches` attribute | HTTP Status 400 with problem description |\n| Invalid patch operations | Send body with invalid JSON patches in `patches` attribute | HTTP Status 400 with problem description |\n| Missing X-Request-ID | `id`=`9000000009` (or any other valid NHS number) | HTTP Status 400 with problem description |\n\nYou can try out the sandbox by selecting the 'Try' button at the end of the schema.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n","summary":"Update patient details","operationId":"update-patient-partial","parameters":[{"in":"header","name":"If-Match","description":"Latest known version identifier enclosed in quotes preceded by `W/`.\n\nSend the value of the patient's `ETag` response header on patient retrieval when updating a patient.\nThis is to ensure that any updates are applied against an up-to-date version of the patient resource.\n","required":true,"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""}},{"in":"header","name":"Content-Type","description":"For a PATCH request, this must be set to `application/json-patch+json`.\n","required":true,"schema":{"type":"string","example":"application/json-patch+json"}}],"requestBody":{"required":true,"content":{"application/json-patch+json":{"schema":{"type":"object","required":["patches"],"properties":{"patches":{"type":"array","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["remove","add","replace","test"]},"path":{"description":"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.","type":"string","format":"jsonpointer","externalDocs":{"description":"IETF RFC 6901 JavaScript Object Notation (JSON) Pointer.","url":"https://tools.ietf.org/html/rfc6901"}},"value":{"description":"The information to be added or replaced. Should not be included on a remove.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"object"}]}}}}}},"examples":{"add-deceased-date-time":{"summary":"Add a new single item (deceasedDateTime) to the patient","value":{"patches":[{"op":"add","path":"/deceasedDateTime","value":"2010-10-22T00:00:00+00:00"}]}},"add-name":{"summary":"Add a new list item (name) to the patient","value":{"patches":[{"op":"add","path":"/name/-","value":{"use":"old","period":{"start":"2019-12-31"},"prefix":["Dr"],"given":["Joe","Horation","Maximus"],"family":"Bloggs","suffix":["PhD"]}}]}},"add-extension":{"summary":"Add a an extension (nominated pharmacy) to the Patient","value":{"patches":[{"op":"add","path":"/extension/-","value":{"url":"https://fhir.hl7.org.uk/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-gender":{"summary":"Update the simple item (gender)","value":{"patches":[{"op":"replace","path":"/gender","value":"male"}]}},"update-address":{"summary":"Update specific fields on a list item (address)","value":{"patches":[{"op":"replace","path":"/address/0/id","value":"456"},{"op":"replace","path":"/address/0/line/0","value":"2 Whitehall Quay"},{"op":"replace","path":"/address/0/postalCode","value":"LS1 4BU"}]}},"update-address-alternative":{"summary":"Update whole object on a list item (address)","value":{"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.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"9876543"}]}]}}]}},"update-extension":{"summary":"Update an extension (death notification)","value":{"patches":[{"op":"replace","path":"/extension/3","value":{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","extension":[{"url":"deathNotificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus","version":"1.0.0","code":"1","display":"Informal - death notice received via an update from a local NHS Organisation such as GP or Trust"}]}}]}}]}},"delete-gender":{"summary":"Remove a single item (gender) no longer in use","value":{"patches":[{"op":"remove","path":"/gender"}]}},"delete-name":{"summary":"Remove a list item (name) no longer in use, using test pointing to the name items id","value":{"patches":[{"op":"test","path":"/name/0/id","value":"123"},{"op":"remove","path":"/name/0"}]}},"delete-name-alternative":{"summary":"Remove a list item (name) no longer in use, using test pointing to the name object","value":{"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"}]}},"delete-extension":{"summary":"Remove an extension (dispensing doctor pharmacy) no longer in use","value":{"patches":[{"op":"test","path":"/extension/1/url","value":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization"},{"op":"remove","path":"/extension/1"}]}}}}}},"responses":{"200":{"description":"Patient updated.","headers":{"ETag":{"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""},"description":"Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/\"2\"`.\n\nCorresponds to `meta.versionId` attribute in the patient resource body.\n\nWhen 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).\nYou must then pass the resource's version number in any update request (in the `If-Match` response header) made for the patient.\n"},"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"id":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"identifier":{"type":"array","description":"Identifier and system of identification used for this Patient.","maxItems":1,"items":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","description":"System identifier belongs to.","default":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"extension":{"type":"array","description":"FHIR extensions.","items":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}}}}}},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The NHS Digital assigned version of the patient resource.","example":"2"},"security":{"type":"array","description":"The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:\n* U - unrestricted. All available data is returned.\n* R - restricted. Any sensitive data around the patient's location, so `address`, `generalPractitioner` and `telecom`, are removed from the response.\n* REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.\n","maxItems":1,"items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the value set specification.","example":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality"},"code":{"type":"string","description":"Code defined by the system value set.","enum":["U","R","V","REDACTED"],"example":"U"},"display":{"type":"string","description":"Representation defined by the system.","enum":["unrestricted","restricted","redacted"],"example":"unrestricted"}}}}}},"name":{"type":"array","description":"List of names associated with the patient. This may not appear if the patient is tagged as `restricted` (also known as a sensitive patient). \n","minItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"multipleBirthInteger":{"type":"integer","minimum":1,"maximum":9,"description":"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.\n\nThere are two other valid values; `8` meaning `Not applicable` and `9` meaning `Not known`.\n","example":1},"deceasedDateTime":{"description":"The date and time in UTC on which a person died or is officially deemed to have died, if applicable and known.\n\nIt is a datetime in the format `yyyy-mm-ddTHH:MM:SS+00:00` or `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.\n","example":"2010-10-22T00:00:00+00:00","type":"string","format":"date-time","pattern":"^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T\\d{2}:\\d{2}:\\d{2}\\+00:00)$|^([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]))$"},"address":{"type":"array","description":"List of addresses associated with the patient.\n\nThese are fully populated on a retrieval or a successful update, only the `home` address is returned on a search.\nWhen a patient tagged as `restricted` is retrieved, all addresses are removed from the response.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient, like phone numbers or email addresses. A patient should only have one instance of each telecom system and use combination on their record at a time. For example, to add a new work email value to the record, the existing work email value should be replaced with the new value. When a patient tagged as `restricted` is retrieved, all contact points, like phone numbers or email addresses, are removed from the response.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"contact":{"type":"array","description":"A list of patient contacts. Only emergency contacts are returned and only emergency contacts should be added. Any other contacts should be added to the patients `Related Person`.\nPatients designate here any contact number they desire to be used in case of an emergency.\nNote, 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.\nWhen a patient tagged as `restricted` is retrieved, all contacts are removed from the response.\n","items":{"title":"Schema for a patient contact.","type":"object","additionalProperties":false,"required":["relationship","telecom"],"properties":{"id":{"type":"string","example":"C123"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"relationship":{"type":"array","description":"The contact relationship wrapper object that holds the details of the relationship to the patient.\n\nThis is only returned when an Emergency Contact number has been set on `telecom`. The only valid code is `C`, which means `Emergency Contact`.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}}},"telecom":{"type":"array","description":"List of Telecom objects on the contact only contains `system` and `value`.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}}}}},"generalPractitioner":{"type":"array","maxItems":1,"description":"General Practice (not practitioner) with which the patient is, or was, registered. Always contains zero or one general practitioner object.\nWhen a patient tagged as `restricted` is retrieved, the General Practice is removed from the response.\n","items":{"description":"General practice (not practitioner) with which the patient is or was registered.","type":"object","required":["identifier"],"properties":{"id":{"description":"Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.","type":"string","example":"254406A3"},"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}}},"managingOrganization":{"description":"The managing organization of a de-registered patient. This will not be returned when the reason for de-registration is death.","type":"object","required":["identifier"],"properties":{"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}},"extension":{"type":"array","description":"Wrapper array for the patient's pharmacies, death notification status, communication details, contact preferences and place of birth; these are all FHIR extensions.\nAlways 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.\nWhen a patient tagged as `restricted` is retrieved, the pharmacy and birth place extensions are removed from the response.\n","items":{"anyOf":[{"type":"object","description":"Wrapper object for the patient's nominated pharmacy. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-NominatedPharmacy FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy"]},"valueReference":{"type":"object","description":"Reference to a pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's nominated pharmacy organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the nominated pharmacy, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y12345"}}}}}}},{"type":"object","description":"Wrapper object for the patient's dispensing doctor. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-DispensingDoctor FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization"]},"valueReference":{"type":"object","description":"Reference to a GP practice pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's dispensing doctor organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the dispensing doctor, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y23456"}}}}}}},{"type":"object","description":"Wrapper object for the patient's medical appliance supplier. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-MedicalApplianceSupplier FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier"]},"valueReference":{"type":"object","description":"Reference to medical appliance supplier pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's medical appliance supplier organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the medical appliance supplier, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y34567"}}}}}}},{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for place of birth details. This will not be returned on a restricted patient.","required":["url","valueAddress"],"properties":{"url":{"type":"string","description":"Definition of place of birth extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","enum":["http://hl7.org/fhir/StructureDefinition/patient-birthPlace"]},"valueAddress":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string","description":"Town or city of birth.","example":"Manchester"},"district":{"type":"string","description":"County or metropolitan district of birth.","example":"Greater Manchester"},"country":{"type":"string","description":"A coded value for a patient's country of birth.\n\nFrom [ISO 3166-1](http://hl7.org/fhir/valueset-iso3166-1-3.html) plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.\n\nUK Internal Codes:\n* `1` - England\n* `2` - Scotland\n* `3` - Wales\n* `4` - Northern Ireland\n* `7` - Sark\n* `9` - Alderney\n* `10` - Channel Islands\n","example":"GBR"}}}}},{"type":"object","description":"An extension to carry the reason a PDS record has been removed from the Patient Demographic Service. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the removal from registration extension.","example":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","enum":["https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration"],"readOnly":true},"extension":{"type":"array","description":"An extension reason a PDS record has been removed from the Patient Demographic Service.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for removalFromRegistrationCode.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"To identify the removal reason code.","example":"removalFromRegistrationCode","enum":["removalFromRegistrationCode"],"readOnly":true},"valueCodeableConcept":{"type":"object","description":"PDS Removal Reason Exit Code","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one removal reason exit code object","items":{"type":"object","required":["system","code","display"],"properties":{"system":{"type":"string","format":"url","description":"URL of the Removal Reason Exit Code. Always uses the 'PDS-RemovalReasonExitCode' Code System.","example":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","readOnly":true},"code":{"type":"string","example":"SCT","enum":["DEA","EMB","SCT","NIT","TRA","ORR"],"description":"A CodeSystem that identifies the reason a PDS record has been removed:\n* `DEA` - Death\n* `EMB` - Embarkation\n* `SCT` - Transferred to Scotland\n* `NIT` - Transferred to Northern Ireland\n* `TRA` - Temporary resident not returned\n* `ORR` - Other reason\n"},"display":{"type":"string","description":"Display-friendly representation of the removal reason exit code.","example":"Transferred to Scotland"}}}}}}}},{"type":"object","description":"Wrapper object for removal from registration effective time.","required":["url","valuePeriod"],"properties":{"url":{"type":"string","description":"Key of this object. Always `effectiveTime`.","example":"effectiveTime","enum":["effectiveTime"],"readOnly":true},"valuePeriod":{"type":"object","description":"The effective time of removal of the Patient record from PDS.","required":["start"],"properties":{"start":{"type":"string","format":"date-time","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2020-01-01T00:00:00+00:00"},"end":{"type":"string","format":"date-time","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2021-12-31T00:00:00+00:00"}}}}}]}}}}]}}}},"example":{"resourceType":"Patient","id":"9000000009","identifier":[{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus","version":"1.0.0","code":"01","display":"Number present and verified"}]}}]}],"meta":{"versionId":"2","security":[{"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality","code":"U","display":"unrestricted"}]},"name":[{"id":"123","use":"usual","period":{"start":"2024-01-01","end":"2025-12-31"},"given":["Jane"],"family":"Smith","prefix":["Mrs"],"suffix":["MBE"]}],"gender":"female","birthDate":"2010-10-22","multipleBirthInteger":1,"deceasedDateTime":"2010-10-22T00:00:00+00:00","generalPractitioner":[{"id":"254406A3","type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345","period":{"start":"2024-01-01","end":"2025-12-31"}}}],"managingOrganization":{"type":"Organization","identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345","period":{"start":"2024-01-01","end":"2025-12-31"}}},"extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y12345"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y23456"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","valueReference":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"Y34567"}}},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","extension":[{"url":"deathNotificationStatus","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus","version":"1.0.0","code":"2","display":"Formal - death notice received from Registrar of Deaths"}]}},{"url":"systemEffectiveDate","valueDateTime":"2010-10-22T00:00:00+00:00"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","extension":[{"url":"language","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage","version":"1.0.0","code":"fr","display":"French"}]}},{"url":"interpreterRequired","valueBoolean":true}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","extension":[{"url":"PreferredWrittenCommunicationFormat","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","code":"12","display":"Braille"}]}},{"url":"PreferredContactMethod","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","code":"1","display":"Letter"}]}},{"url":"PreferredContactTimes","valueString":"Not after 7pm"}]},{"url":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","valueAddress":{"city":"Manchester","district":"Greater Manchester","country":"GBR"}},{"url":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","extension":[{"url":"removalFromRegistrationCode","valueCodeableConcept":{"coding":[{"system":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","code":"SCT","display":"Transferred to Scotland"}]}},{"url":"effectiveTime","valuePeriod":{"start":"2020-01-01T00:00:00+00:00","end":"2021-12-31T00:00:00+00:00"}}]}],"telecom":[{"id":"789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"phone","value":"01632960587","use":"home"},{"id":"790","period":{"start":"2019-01-01","end":"2022-12-31"},"system":"email","value":"jane.smith@example.com","use":"home"},{"id":"OC789","period":{"start":"2024-01-01","end":"2025-12-31"},"system":"other","value":"01632960587","use":"home","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem","code":"textphone","display":"Minicom (Textphone)"}}]}],"contact":[{"id":"C123","period":{"start":"2024-01-01","end":"2025-12-31"},"relationship":[{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/v2-0131","code":"C","display":"Emergency Contact"}]}],"telecom":[{"system":"phone","value":"01632960587"}]}],"address":[{"id":"456","period":{"start":"2024-01-01","end":"2025-12-31"},"use":"home","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]},{"id":"T456","period":{"start":"2024-01-01","end":"2025-12-31"},"use":"temp","text":"Student Accommodation","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]}]}}}},"503":{"description":"The request timed out during processing. This does not imply the request has failed or been rejected. Error code: `SERVICE_UNAVAILABLE`.\n\nRe-send the request after the time specified in the `Retry-After` header using the same `X-Request-ID` value.\n","headers":{"RetryAfter":{"description":"Time to wait between polls in seconds","schema":{"type":"string","example":"5"}}},"content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"timeout","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"SERVICE_UNAVAILABLE","display":"Service unavailable"}]},"diagnostics":"The downstream domain processing has not completed within the configured timeout period. Using the same 'X-Request-ID' header, retry your request after the time specified by the 'Retry-After' response header."}]}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | --------------------------------------------- |\n| 400 | UNSUPPORTED_SERVICE | Missing NHS number. |\n| 400 | MISSING_VALUE | Missing header parameter. For details, see the `diagnostics` field. |\n| 400 | INVALID_VALUE | Invalid header parameter or invalid value in body of patch request. For details, see the `diagnostics` field. |\n| 400 | INVALID_UPDATE | Malformed patch request or client error after the patch was accepted and patient was not updated. For example, a start date was after the corresponding end date. |\n| 400 | INVALID_RESOURCE_ID | Invalid NHS number. |\n| 400 | VALIDATION_ERROR | This is the \"default\" error thrown when no others are applicable. |\n| 400 | UNSUPPORTED_CHARACTERS_IN_FIELD | Invalid value in body of patch request. For details, see the `diagnostics` field. |\n| 400 | ADDITIONAL_PROPERTIES | 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. |\n| 400 | UNSUPPORTED_VALUE | 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. |\n| 400 | TOO_FEW_VALUES_SUBMITTED | The field in question has a minimum number of items and the user sent too few. |\n| 400 | TOO_MANY_VALUES_SUBMITTED | The field in question has a maximum number of items and the user sent too many. |\n| 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. |\n| 403 | FORBIDDEN_UPDATE | The user is not permitted to update certain resources or elements, for example most users are not allowed to update the date of death once it has been set. 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. |\n| 403 | ACCESS_DENIED | Patient cannot perform this action. |\n| 404 | RESOURCE_NOT_FOUND | Patient does not exist for given NHS number. |\n| 404 | INVALIDATED_RESOURCE | Patient record for given NHS number has been invalidated and not superseded by another NHS number. |\n| 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. |\n| 409 | RESOURCE_VERSION_MISMATCH | The resource version in the `If-Match` header of the update request did not match the current version of the resource. See [Patient resource versioning](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir#patient-resource-versioning). |\n| 412 | PRECONDITION_FAILED | Problem with request, for example missing `If-Match` header. For details, see the `diagnostics` field. |\n| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"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 - Update unsupported for resource - 'pets'"}]}}}}}}},"/Patient/{id}/RelatedPerson":{"get":{"parameters":[{"name":"id","in":"path","description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","required":true,"schema":{"type":"string","example":"9000000009"}},{"in":"header","name":"Authorization","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\n\nRequired in all environments except sandbox.\n","required":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"in":"header","name":"NHSD-Session-URID","description":"\nThe user role ID (URID) for the current session. Also known as a user role profile ID (URPID).\n\nThis header is optional.\n\nIn Application-restricted and Patient access mode this header is ignored.\n\nIn Healthcare worker access mode if you send this header it must be valid for the logged-in user. See [determine the user's role](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation#step-9-determine-the-user-s-role) for guidance.\n","required":false,"schema":{"type":"string","pattern":"^[0-9]+$","example":"555254240100"}},{"in":"header","name":"X-Request-ID","required":true,"description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\n\nMust be a universally unique identifier (UUID) (ideally version 4).\n\nMirrored back in a response header.\n\nThis is a mandatory header.\n\nIf you re-send a failed request, use the same value in this header.\n","schema":{"type":"string","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"}},{"in":"header","name":"X-Correlation-ID","required":false,"description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\n\nMirrored back in a response header.\n","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"in":"header","name":"NHSD-End-User-Organisation-ODS","required":false,"description":"The ODS code of the user.\n\nMandatory for client applications which service multiple end user organisations (EUO). This will allow the calls to be attributed to the correct EUO.\n","schema":{"type":"string","example":"Y12345"}}],"description":"## Overview\nUse 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.\n\n## Restricted patients\nSome patients are tagged as [restricted](https://digital.nhs.uk/services/demographics/restricting-access-to-a-patients-demographic-record) and are sometimes known as sensitive patients. Related people are not returned for a restricted patient and an empty bundle is returned.\n\nIf a related person only contains a patient reference, and when the patient is retrieved, it is restricted; location sensitive fields such as `address` and `telecom` are removed.\n\n## Sandbox test scenarios\nYou can test the following scenarios in our sandbox environment:\n\n| Scenario | Request | Response |\n| ------------------------------- | --------------------------------------------- | ------------------------------------------------------------- |\n| Multiple related people exists | `id`=`9000000009` | HTTP Status 200 with related person data in a response Bundle |\n| Single related person exists | `id`=`9000000017` | HTTP Status 200 with related person data in a response Bundle |\n| Related people do not exist | `id`=`9000000025` | HTTP Status 200 with an empty bundle |\n| Missing X-Request-ID | `id`=`9000000009` (or any other valid NHS number) | HTTP Status 400 with problem description |\n\nYou can try out the sandbox by selecting the 'Try' button at the end of the schema.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n","summary":"Get a patient's related people","operationId":"get-related-people","responses":{"200":{"description":"Information successfully returned.","headers":{"ETag":{"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""},"description":"Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/\"2\"`.\n\nCorresponds to `meta.versionId` attribute in the patient resource body.\n\nWhen 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).\nYou must then pass the resource's version number in any update request (in the `If-Match` response header) made for the patient.\n"},"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"Bundle"},"type":{"type":"string","description":"FHIR Bundle Type.","default":"searchset"},"timestamp":{"type":"string","description":"Time the search was performed, including the year, month, date, time and timezone, in the format YYYY-MM-DDThh:mm:ss+hh:mm.","format":"datetime","example":"2019-12-25T12:00:00+00:00"},"total":{"type":"integer","description":"Number of resources returned in search.","example":1},"entry":{"type":"array","description":"A list of related people details attached to the patient. \n","items":{"type":"object","properties":{"fullUrl":{"type":"string","description":"Absolute URL of the resource described in this item.","example":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009/RelatedPerson/507B7621"},"resource":{"type":"object","additionalProperties":false,"required":["patient","relationship"],"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"507B7621"},"resourceType":{"type":"string","description":"FHIR resource type.","default":"RelatedPerson"},"patient":{"type":"object","properties":{"identifier":{"type":"object","description":"Identifier and system of identification used for this Patient.\n\nThis 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.\n","properties":{"system":{"type":"string","default":"https://fhir.nhs.uk/Id/nhs-number","description":"URL for the Patient retrieval API.","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"]},"value":{"type":"string","description":"NHS number for the related person","example":"9000000009","pattern":"^\\d{10}$"}}}}},"active":{"type":"boolean","default":true},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"name":{"type":"array","description":"List containing zero or one name associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\nIf no `patient` reference is available `name` and `address` must be provided at the minimum.\n","maxItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"address":{"type":"array","description":"List containing zero or one address associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\nIf no `patient` reference is available `name` and `address` must be provided at the minimum.\n","maxItems":1,"items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List containing zero to five contact methods associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\n","maxItems":5,"items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"relationship":{"type":"array","description":"The relationship of the related person to the patient.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Coded values for three relationship types:\n* Role\n* Type\n* Next-of-Kin\n\nThe codes used can be found at:\n* http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype\n* https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole\n\nThe allowed values for `Role` are:\n* Agent - Agent of patient\n* Guardian - Guardian of patient\n* Personal - Personal relationship with the patient\n\nThe allowed values for `Type` are:\n* SPS - spouse\n* DOMPART - domestic partner\n* PRN - parent\n* PRNFOST - foster parent\n* STPPRN - step parent\n* CHILD - child\n* MTH - mother\n* FTH - father\n* SIS - sister\n* BRO - brother\n* FAMMEMB - family member\n* ONESELF - self\n* N - Next-of-Kin\n* U - Unknown\n* PolygamousPartner - Polygamous Partner of patient\n* Dependant - Dependant of patient\n* NonDependant - Non Dependant of patient\n* ProxyContact - Proxy Contact for patient\n* ProxyCommunication - Proxy Communication for patient\n* ProxyContactCommunication - Proxy Contact and Communication for patient\n* Carer - Carer of patient\n* Guardian - Guardian of patient\n* NotSpecified - Not Specified\n\nThe allowed values for `Next-of-Kin` are:\n* N - Next-of-Kin\n\n`Role` and `Type` are mandatory, so both should be present - however they both contain the `Guardian` code - so a single response is possible.\n\n`Next-of-Kin` is optional and will be absent from the response when the related person is not the Next-of-Kin.\n","minItems":1,"maxItems":3,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","format":"url","example":"https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole","enum":["http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype","https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole"]},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"Guardian"},"display":{"type":"string","description":"Human-friendly display representation defined by the system.","example":"Guardian of patient"}}}}}}},"extension":{"type":"array","description":"Wrapper array for copy correspondence, contact rank, contact preferences and communication details; these are all FHIR extensions. Always contains zero or one of each extension type.\n","items":{"anyOf":[{"type":"object","description":"Flag indicating if this person should be copied in on any contact with the Patient. This will only be returned if the value is true and the person should be copied in on correspondence, otherwise it will be omitted. \n","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator"]},"valueBoolean":{"type":"boolean","description":"Flag indicating if this person should be copied in on correspondence. This will only be returned if the value is `true` otherwise it will not be returned and can be assumed `false`","example":true}}},{"type":"object","description":"Rank indicating order in which contacts should be tried.","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank"]},"valuePositiveInt":{"type":"integer","minimum":1,"maximum":99,"description":"Rank expressed as positive integer (1 being the highest).","example":1}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}}]}}}}}}}}},"example":{"resourceType":"Bundle","type":"searchset","timestamp":"2019-12-25T12:00:00+00:00","total":1,"entry":[{"fullUrl":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009/RelatedPerson/507B7621","resource":{"id":"507B7621","resourceType":"RelatedPerson","patient":{"identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009"}},"active":true,"period":{"start":"2024-01-01","end":"2025-12-31"},"name":[{"use":"usual","period":{"start":"2024-01-01","end":"2025-12-31"},"given":["Jane"],"family":"Smith","prefix":["Mrs"],"suffix":["MBE"]}],"relationship":[{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole","code":"Guardian","display":"Guardian of patient"}]}],"extension":[{"url":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator","valueBoolean":true},{"url":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank","valuePositiveInt":1},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","extension":[{"url":"PreferredWrittenCommunicationFormat","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","code":"12","display":"Braille"}]}},{"url":"PreferredContactMethod","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","code":"1","display":"Letter"}]}},{"url":"PreferredContactTimes","valueString":"Not after 7pm"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","extension":[{"url":"language","valueCodeableConcept":{"coding":[{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage","version":"1.0.0","code":"fr","display":"French"}]}},{"url":"interpreterRequired","valueBoolean":true}]}],"telecom":[{"period":{"start":"2024-01-01","end":"2025-12-31"},"system":"phone","value":"01632960587","use":"home"}],"address":[{"period":{"start":"2024-01-01","end":"2025-12-31"},"use":"home","line":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"],"postalCode":"LS1 6AE","extension":[{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"PAF"}},{"url":"value","valueString":"12345678"}]},{"url":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","extension":[{"url":"type","valueCoding":{"system":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType","code":"UPRN"}},{"url":"value","valueString":"123456789012"}]}]}]}}]}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | --------------------------------------------- |\n| 400 | INVALID_RESOURCE_ID | Invalid NHS number. |\n| 400 | MISSING_VALUE | Missing header parameter. For details, see the `diagnostics` field. |\n| 400 | INVALID_VALUE | Invalid header parameter. For details, see the `diagnostics` field. |\n| 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation. |\n| 404 | RESOURCE_NOT_FOUND | No related people exist for given NHS number. |\n| 404 | INVALIDATED_RESOURCE | Patient record for given NHS number has been invalidated and not superseded by another NHS number. |\n| 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. |\n| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"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":"Invalid request with error - X-Request-ID header must be supplied to access this resource"}]}}}}}}},"/Coverage":{"get":{"summary":"Get a patient's coverage","operationId":"get-coverage","description":"## Overview\nUse this endpoint to get a patient's European Health Insurance Card (EHIC) details. Use the patient's NHS number as the identifier for coverage.\n\nThis endpoint only gives EHIC data in the coverage data fields. A patient may have other financial coverage, like insurance, but this information will not be returned by PDS. \n\nYou can only use this endpoint if you are using patient access mode (for specific use cases only). \n\nIf EHIC details are stored on PDS but the personal ID or institution ID are missing then the entire EHIC record will not be returned. \n \n## Superseded patients\nSome patients are marked as superseded. This means that the original patient NHS number is no longer valid and has been replaced with a different NHS number.\n\nWhen PDS tries to get the EHIC details using the NHS number of a superseded record, it will return the EHIC details of the retained record. This can be seen by comparing the returned NHS number with the NHS number submitted in the request.\n\n## Sandbox test scenarios\n You can test the following scenarios in our sandbox environment:\n\n | Scenario | Request | Response |\n | --------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ |\n | Coverage details exist for the patient | `id`=`9000000009` | HTTP Status 200 with patient coverage details in response |\n | Coverage details do not exist for the patient | `id`=`9000000033` | HTTP Status 200 with no patient coverage details in response |\n | Invalid Search criteria | `id`=`9999999990`, `year`=`2003` | HTTP Status 400 with problem description |\n | Missing X-Request-ID | `id`=`9000000009` | HTTP Status 400 with problem description |\n | Invalid X-Request-ID | X-Request-ID=1234 | HTTP Status 400 with problem description |\n\n You can try out the sandbox by selecting the 'Try' button at the end of the schema.\n\n Alternatively, you can try out the sandbox using our Postman collection:\n \n [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n","parameters":[{"name":"subscriber:identifier","description":"The NHS number that identifies the holder/subscriber of the coverage.\n","examples":{"ehic_holder":{"value":9000000009,"summary":"Returns a bundle that contains a Coverage resource for the patient with NHS number 9733162868."},"no_ehic":{"value":9000000033,"summary":"Returns an empty bundle, alongside a meta object that can be used to apply an update to the patient's coverage."}},"in":"query","required":true,"schema":{"type":"string"}},{"in":"header","name":"Authorization","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\n\nRequired in all environments except sandbox.\n","required":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"in":"header","name":"X-Request-ID","required":true,"description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\n\nMust be a universally unique identifier (UUID) (ideally version 4).\n\nMirrored back in a response header.\n\nThis is a mandatory header.\n\nIf you re-send a failed request, use the same value in this header.\n","schema":{"type":"string","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"}},{"in":"header","name":"X-Correlation-ID","required":false,"description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\n\nMirrored back in a response header.\n","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"in":"header","name":"NHSD-End-User-Organisation-ODS","required":false,"description":"The ODS code of the user.\n\nMandatory for client applications which service multiple end user organisations (EUO). This will allow the calls to be attributed to the correct EUO.\n","schema":{"type":"string","example":"Y12345"}}],"responses":{"200":{"description":"A completed search for coverage. This will contain zero or one Coverage resources in the Bundle.\n","headers":{"ETag":{"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""},"description":"Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/\"2\"`.\n\nCorresponds to `meta.versionId` attribute in the patient resource body.\n\nWhen 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).\nYou must then pass the resource's version number in any update request (in the `If-Match` response header) made for the patient.\n"},"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","enum":["Bundle"],"default":"Bundle"},"type":{"type":"string","description":"FHIR Bundle Type.","enum":["searchset"],"default":"searchset"},"timestamp":{"type":"string","description":"Time the search was performed.","format":"datetime","example":"2019-12-25T12:00:00+00:00"},"total":{"type":"integer","description":"Number of resources returned in search.","minimum":0,"maximum":1,"example":1},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The current version number of the coverage details.","pattern":"^\\d+$","example":"2"}}},"entry":{"type":"array","description":"A list of matched coverages. Empty if none found.\n","items":{"type":"object","properties":{"fullUrl":{"type":"string","example":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Coverage?subscriber:identifier=9000000009"},"resource":{"description":"Insurance or medical plan or a payment agreement","type":"object","required":["status","beneficiary","payor","subscriber","identifier","period"],"properties":{"resourceType":{"type":"string","enum":["Coverage"],"example":"Coverage"},"status":{"type":"string","description":"The status of the resource instance.","enum":["active"],"example":"active"},"subscriber":{"type":"object","description":"Subscriber and patient covered by the policy. For EHIC, this is the patient's NHS number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"],"example":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"}}}}},"identifier":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["value","assigner"],"properties":{"value":{"type":"string","description":"The primary identifier of the insurer. For EHIC, this is the identification number of the card.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"29401395498043123948"},"assigner":{"description":"Identifier for the country that the coverage is from, in the format of the [International Organization for Standardization (ISO) three digital letter combination](https://www.gov.uk/government/publications/iso-country-codes--2) (ISO alpha-3). For EHIC, this is the country of issue.","type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["system","value"],"properties":{"system":{"type":"string","enum":["urn:iso:std:iso:3166"],"example":"urn:iso:std:iso:3166"},"value":{"type":"string","description":"Three-letter country code that identifies the country from which the Coverage originates.","example":"FRA","pattern":"^[A-Z]{3}$"}}},"display":{"type":"string","description":"Display-friendly representation of the country code.","readOnly":true,"example":"France"}}}}}},"payor":{"type":"array","description":"Issuer of the policy. For EHIC, this is the identification number of the institution.","minItems":1,"maxItems":1,"items":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The value that is unique","minLength":1,"maxLength":30,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,30}$","example":"92847ADGJL"}}}}}},"beneficiary":{"type":"object","description":"Plan beneficiary. For EHIC, this is the personal identification number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The personal ID number identifying the beneficiary.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"178705ABC"}}}}},"period":{"type":"object","description":"Time period when coverage is valid. For EHIC, this is the expiry date.","required":["end"],"properties":{"end":{"type":"string","format":"date","description":"End date of time period, if known, in format `yyyy-mm-dd`. Must be less than 150 years in the past. Must be less than 150 years in the future.","example":"2030-12-31"}}}}}}}}}},"example":{"resourceType":"Bundle","type":"searchset","timestamp":"2019-12-25T12:00:00+00:00","total":1,"meta":{"versionId":"2"},"entry":[{"fullUrl":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Coverage?subscriber:identifier=9000000009","resource":{"resourceType":"Coverage","status":"active","subscriber":{"identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009"}},"identifier":[{"value":"29401395498043123948","assigner":{"identifier":{"system":"urn:iso:std:iso:3166","value":"FRA"},"display":"France"}}],"payor":[{"identifier":{"value":"92847ADGJL"}}],"beneficiary":{"identifier":{"value":"178705ABC"}},"period":{"end":"2030-12-31"}}}]}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| 400 | INVALID_RESOURCE_ID | Invalid NHS number. |\n| 400 | INVALID_SEARCH_DATA\t | Invalid combination of search parameters. For details, see the `diagnostics` field. |\n| 400 | MISSING_VALUE | Missing header or query parameter. For details, see the `diagnostics` field. |\n| 400 | INVALID_VALUE | Invalid header or query parameter. For details, see the `diagnostics` field. |\n| 401 | ACCESS_DENIED \t | Access token missing, invalid or expired, or calling application not configured for this operation. |\n| 403 | ACCESS_DENIED \t | User cannot perform this operation. |\n| 404 | RESOURCE_NOT_FOUND | Patient does not exist for given NHS number. |\n| 404 | INVALIDATED_RESOURCE | Patient did exist for given NHS number, but has been invalidated and not superseded by another NHS number. |\n| 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. |\n| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"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 - 'Coverage search request must follow the format /Coverage?subscriber:identifier=NHS_NUMBER'"}]}}}}}},"post":{"summary":"Update a patient's coverage","operationId":"post-coverage","description":"## Overview\nUse this endpoint to update a patient's European Health Insurance Card (EHIC) details. A patient may have other financial coverage, like insurance, but this information cannot be added to PDS. \n\nThere can only be one set of EHIC details on a patient's record at a time. If a patient already has an EHIC record in PDS, the update request will replace the existing EHIC record. When a user adds a new EHIC record to PDS, they must enter information for all the EHIC data fields. \n\nYou can only update EHIC details using patient access mode (for specific use cases only). \n\n## Patient resource versioning\nTo update a patient's details, use the `get a patient's coverage` operation to get a version number for the most up-to-date details. The version number is in the `ETag` response header in the form `W/\"2\"`.\n\nYou must then pass the patient's version number in the update request, in the `If-Match` response header. If the coverage details have been updated in PDS between your first retrieval and the update request, the update will fail.\n\nWhen the update succeeds, you will get the updated coverage details. This will contain the new resource version number.\n\nIf you make a further update you must use the new version number.\n\n## Sandbox test scenarios\n\nYou can test the following scenarios in our sandbox environment.\n\n| Scenario | Request | Response |\n| ----------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ |\n| Add coverage details | `id`=`9000000009`

Body: One of the provided examples or your own combination

Headers: `If-Match`=`W/\"2\"`, `Content-Type`=`application/json` | HTTP Status 201 with patient coverage details in response |\n| Incorrect resource version | `If-Match`=`W/\"1\"` | HTTP Status 409 with problem description |\n| Missing resource version identifier | `If-Match` header missing | HTTP Status 412 with problem description |\n| Missing Ehic card number | `id`=`9000000009`

Body: One of the provided examples or your own combination

Headers: `If-Match`=`W/\"2\"`, `Content-Type`=`application/json` | HTTP Status 400 with problem description |\n| Invalid NHS number | `id`=`9000000000` (or any invalid NHS number) | HTTP Status 400 with problem description |\n| Missing X-Request-ID | X-Request-ID header missing | HTTP Status 400 with problem description |\n| Invalid X-Request-ID | `X-Request-ID`= `1234` | HTTP Status 400 with problem description |\n\nYou can try out the sandbox by selecting the 'Try' button at the end of the schema.\n\nAlternatively, you can try out the sandbox using our Postman collection:\n\n[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/32547823-005ebee4-7510-44c3-bb0e-58f26b2ba747)\n","parameters":[{"in":"header","name":"If-Match","description":"Latest known version identifier enclosed in quotes preceded by `W/`.\n\nSend the value of the patient's `ETag` response header on patient retrieval when updating a patient.\nThis is to ensure that any updates are applied against an up-to-date version of the patient resource.\n","required":true,"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""}},{"in":"header","name":"Authorization","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\n\nRequired in all environments except sandbox.\n","required":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},{"in":"header","name":"X-Request-ID","required":true,"description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\n\nMust be a universally unique identifier (UUID) (ideally version 4).\n\nMirrored back in a response header.\n\nThis is a mandatory header.\n\nIf you re-send a failed request, use the same value in this header.\n","schema":{"type":"string","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"}},{"in":"header","name":"X-Correlation-ID","required":false,"description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\n\nMirrored back in a response header.\n","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},{"in":"header","name":"NHSD-End-User-Organisation-ODS","required":false,"description":"The ODS code of the user.\n\nMandatory for client applications which service multiple end user organisations (EUO). This will allow the calls to be attributed to the correct EUO.\n","schema":{"type":"string","example":"Y12345"}}],"requestBody":{"required":true,"content":{"application/json-patch+json":{"schema":{"description":"Insurance or medical plan or a payment agreement","type":"object","required":["status","beneficiary","payor","subscriber","identifier","period"],"properties":{"resourceType":{"type":"string","enum":["Coverage"],"example":"Coverage"},"status":{"type":"string","description":"The status of the resource instance.","enum":["active"],"example":"active"},"subscriber":{"type":"object","description":"Subscriber and patient covered by the policy. For EHIC, this is the patient's NHS number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"],"example":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"}}}}},"identifier":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["value","assigner"],"properties":{"value":{"type":"string","description":"The primary identifier of the insurer. For EHIC, this is the identification number of the card.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"29401395498043123948"},"assigner":{"description":"Identifier for the country that the coverage is from, in the format of the [International Organization for Standardization (ISO) three digital letter combination](https://www.gov.uk/government/publications/iso-country-codes--2) (ISO alpha-3). For EHIC, this is the country of issue.","type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["system","value"],"properties":{"system":{"type":"string","enum":["urn:iso:std:iso:3166"],"example":"urn:iso:std:iso:3166"},"value":{"type":"string","description":"Three-letter country code that identifies the country from which the Coverage originates.","example":"FRA","pattern":"^[A-Z]{3}$"}}},"display":{"type":"string","description":"Display-friendly representation of the country code.","readOnly":true,"example":"France"}}}}}},"payor":{"type":"array","description":"Issuer of the policy. For EHIC, this is the identification number of the institution.","minItems":1,"maxItems":1,"items":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The value that is unique","minLength":1,"maxLength":30,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,30}$","example":"92847ADGJL"}}}}}},"beneficiary":{"type":"object","description":"Plan beneficiary. For EHIC, this is the personal identification number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The personal ID number identifying the beneficiary.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"178705ABC"}}}}},"period":{"type":"object","description":"Time period when coverage is valid. For EHIC, this is the expiry date.","required":["end"],"properties":{"end":{"type":"string","format":"date","description":"End date of time period, if known, in format `yyyy-mm-dd`. Must be less than 150 years in the past. Must be less than 150 years in the future.","example":"2030-12-31"}}}}},"examples":{"add-coverage-to-patient":{"summary":"Add a coverage to a patient","value":{"resourceType":"Coverage","status":"active","subscriber":{"identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009"}},"identifier":[{"value":"29401395498043123948","assigner":{"identifier":{"system":"urn:iso:std:iso:3166","value":"FRA"},"display":"France"}}],"payor":[{"identifier":{"value":"92847ADGJL"}}],"beneficiary":{"identifier":{"value":"178705ABC"}},"period":{"end":"2030-12-31"}}}}}}},"responses":{"503":{"description":"The request timed out during processing. This does not imply the request has failed or been rejected. Error code: `SERVICE_UNAVAILABLE`.\nRe-send the request after the time specified in the `Retry-After` header using the same `X-Request-ID` value.\n","headers":{"RetryAfter":{"description":"Time to wait between polls in seconds","schema":{"type":"string","example":"5"}},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"timeout","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"SERVICE_UNAVAILABLE","display":"Service unavailable"}]},"diagnostics":"The downstream domain processing has not completed within the configured timeout period. Using the same 'X-Request-ID' header, retry your request after the time specified by the 'Retry-After' response header."}]}}}},"2XX":{"description":"A completed update to coverage. This will contain the Coverage resource just posted in the Bundle.\n | HTTP status | Error code | Description |\n | ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n | 201 | | Coverage successfully added\n","headers":{"ETag":{"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""},"description":"Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/\"2\"`.\n\nCorresponds to `meta.versionId` attribute in the patient resource body.\n\nWhen 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).\nYou must then pass the resource's version number in any update request (in the `If-Match` response header) made for the patient.\n"},"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"content":{"application/fhir+json":{"schema":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","enum":["Bundle"],"default":"Bundle"},"type":{"type":"string","description":"FHIR Bundle Type.","enum":["searchset"],"default":"searchset"},"timestamp":{"type":"string","description":"Time the search was performed.","format":"datetime","example":"2019-12-25T12:00:00+00:00"},"total":{"type":"integer","description":"Number of resources returned in search.","minimum":0,"maximum":1,"example":1},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The current version number of the coverage details.","pattern":"^\\d+$","example":"2"}}},"entry":{"type":"array","description":"A list of matched coverages. Empty if none found.\n","items":{"type":"object","properties":{"fullUrl":{"type":"string","example":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Coverage?subscriber:identifier=9000000009"},"resource":{"description":"Insurance or medical plan or a payment agreement","type":"object","required":["status","beneficiary","payor","subscriber","identifier","period"],"properties":{"resourceType":{"type":"string","enum":["Coverage"],"example":"Coverage"},"status":{"type":"string","description":"The status of the resource instance.","enum":["active"],"example":"active"},"subscriber":{"type":"object","description":"Subscriber and patient covered by the policy. For EHIC, this is the patient's NHS number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"],"example":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"}}}}},"identifier":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["value","assigner"],"properties":{"value":{"type":"string","description":"The primary identifier of the insurer. For EHIC, this is the identification number of the card.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"29401395498043123948"},"assigner":{"description":"Identifier for the country that the coverage is from, in the format of the [International Organization for Standardization (ISO) three digital letter combination](https://www.gov.uk/government/publications/iso-country-codes--2) (ISO alpha-3). For EHIC, this is the country of issue.","type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["system","value"],"properties":{"system":{"type":"string","enum":["urn:iso:std:iso:3166"],"example":"urn:iso:std:iso:3166"},"value":{"type":"string","description":"Three-letter country code that identifies the country from which the Coverage originates.","example":"FRA","pattern":"^[A-Z]{3}$"}}},"display":{"type":"string","description":"Display-friendly representation of the country code.","readOnly":true,"example":"France"}}}}}},"payor":{"type":"array","description":"Issuer of the policy. For EHIC, this is the identification number of the institution.","minItems":1,"maxItems":1,"items":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The value that is unique","minLength":1,"maxLength":30,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,30}$","example":"92847ADGJL"}}}}}},"beneficiary":{"type":"object","description":"Plan beneficiary. For EHIC, this is the personal identification number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The personal ID number identifying the beneficiary.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"178705ABC"}}}}},"period":{"type":"object","description":"Time period when coverage is valid. For EHIC, this is the expiry date.","required":["end"],"properties":{"end":{"type":"string","format":"date","description":"End date of time period, if known, in format `yyyy-mm-dd`. Must be less than 150 years in the past. Must be less than 150 years in the future.","example":"2030-12-31"}}}}}}}}}},"example":{"resourceType":"Bundle","type":"searchset","timestamp":"2019-12-25T12:00:00+00:00","total":1,"meta":{"versionId":"2"},"entry":[{"fullUrl":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Coverage?subscriber:identifier=9000000009","resource":{"resourceType":"Coverage","status":"active","subscriber":{"identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000009"}},"identifier":[{"value":"29401395498043123948","assigner":{"identifier":{"system":"urn:iso:std:iso:3166","value":"FRA"},"display":"France"}}],"payor":[{"identifier":{"value":"92847ADGJL"}}],"beneficiary":{"identifier":{"value":"178705ABC"}},"period":{"end":"2030-12-31"}}}]}}}},"4XX":{"description":"An error occurred as follows:\n\n| HTTP status | Error code | Description |\n| ----------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| 400 | MISSING_VALUE | Missing header or value in the body. For details, see the `diagnostics` field. |\n| 400 | INVALID_VALUE | Invalid header or value in the body. For details, see the `diagnostics` field. \n| 400 | INVALID_UPDATE | Malformed request body or client error after the update was accepted and patient was not updated. |\n| 400 | INVALID_RESOURCE_ID | Invalid NHS number. |\n| 400 | VALIDATION_ERROR | This is the \"default\" error thrown when no others are applicable. |\n| 400\t | TOO_FEW_VALUES_SUBMITTED\t | The field in question has a minimum number of items and the user sent too few. |\n| 400\t | TOO_MANY_VALUES_SUBMITTED\t | The field in question has a maximum number of items and the user sent too many. |\n| 401 | ACCESS_DENIED | Access token missing, invalid or expired, or calling application not configured for this operation (ASID not set for interaction) |\n| 403\t | FORBIDDEN_UPDATE\t | The user is not permitted to update certain resources or elements, for example most users are not allowed to update the date of death once it has been set. 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. |\n| 404 | RESOURCE_NOT_FOUND | Patient does not exist for given NHS number. |\n| 408 | UNABLE_TO_CALL_SERVICE | The downstream domain processing has not completed within the configured timeout period. |\n| 409 | RESOURCE_VERSION_MISMATCH | The resource version in the If-Match header of the update request did not match the current version of the resource. See Patient resource versioning. |\n| 412\t | PRECONDITION_FAILED\t | Problem with request, for example missing If-Match header. For details, see the diagnostics field. |\n| 429 | TOO_MANY_REQUESTS | You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits). |\n","content":{"application/fhir+json":{"schema":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"example":{"resourceType":"OperationOutcome","issue":[{"severity":"error","code":"forbidden","details":{"coding":[{"system":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode","version":"1","code":"ACCESS_DENIED","display":"Patient cannot perform this action"}]},"diagnostics":"Your access token has insufficient permissions. See documentation regarding Patient access restrictions https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir"}]}}}}}}}},"components":{"headers":{"ETag":{"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""},"description":"Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/\"2\"`.\n\nCorresponds to `meta.versionId` attribute in the patient resource body.\n\nWhen 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).\nYou must then pass the resource's version number in any update request (in the `If-Match` response header) made for the patient.\n"},"X-Correlation-Id":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"X-Request-Id":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"},"RetryAfter":{"description":"Time to wait between polls in seconds","schema":{"type":"string","example":"5"}},"XCorrelationId":{"schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"XRequestID":{"schema":{"type":"string","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"},"description":"The X-Request-ID from the request header, if supplied, mirrored back.\n"}},"parameters":{"Id":{"name":"id","in":"path","description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","required":true,"schema":{"type":"string","example":"9000000009"}},"IfMatch":{"in":"header","name":"If-Match","description":"Latest known version identifier enclosed in quotes preceded by `W/`.\n\nSend the value of the patient's `ETag` response header on patient retrieval when updating a patient.\nThis is to ensure that any updates are applied against an up-to-date version of the patient resource.\n","required":true,"schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""}},"RoleId":{"in":"header","name":"NHSD-Session-URID","description":"\nThe user role ID (URID) for the current session. Also known as a user role profile ID (URPID).\n\nThis header is optional.\n\nIn Application-restricted and Patient access mode this header is ignored.\n\nIn Healthcare worker access mode if you send this header it must be valid for the logged-in user. See [determine the user's role](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation#step-9-determine-the-user-s-role) for guidance.\n","required":false,"schema":{"type":"string","pattern":"^[0-9]+$","example":"555254240100"}},"BearerAuthorization":{"in":"header","name":"Authorization","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\n\nRequired in all environments except sandbox.\n","required":false,"schema":{"type":"string","format":"^Bearer\\ [[:ascii:]]+$","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},"ContentType":{"in":"header","name":"Content-Type","description":"For a PATCH request, this must be set to `application/json-patch+json`.\n","required":true,"schema":{"type":"string","example":"application/json-patch+json"}},"RequestID":{"in":"header","name":"X-Request-ID","required":true,"description":"A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests and to trace the request if you contact our helpdesk.\n\nMust be a universally unique identifier (UUID) (ideally version 4).\n\nMirrored back in a response header.\n\nThis is a mandatory header.\n\nIf you re-send a failed request, use the same value in this header.\n","schema":{"type":"string","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"}},"CorrelationID":{"in":"header","name":"X-Correlation-ID","required":false,"description":"An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.\n\nMirrored back in a response header.\n","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"}},"NHSD-End-User-Organisation-ODS":{"in":"header","name":"NHSD-End-User-Organisation-ODS","required":false,"description":"The ODS code of the user.\n\nMandatory for client applications which service multiple end user organisations (EUO). This will allow the calls to be attributed to the correct EUO.\n","schema":{"type":"string","example":"Y12345"}},"FuzzyMatch":{"name":"_fuzzy-match","description":"A fuzzy search is performed, including checks for homophones, transposed names and historic information.\n\nYou cannot use wildcards with a fuzzy search.\n","example":false,"in":"query","required":false,"schema":{"type":"boolean","default":false}},"ExactMatch":{"name":"_exact-match","description":"The search only returns results where the `score` field is 1.0. Use this with care - it is unlikely to work with fuzzy search or wildcards.","example":false,"in":"query","required":false,"schema":{"type":"boolean","default":false}},"History":{"name":"_history","description":"The search looks for matches in historic information such as previous names and addresses.\n\nThis parameter has no effect for a fuzzy search, which always includes historic information.\n","example":false,"in":"query","required":false,"schema":{"type":"boolean","default":false}},"MaxResults":{"name":"_max-results","description":"The maximum number of matching patients to return. For healthcare worker access, this must be between 1 and 50, and the default is 50.\nFor application-restricted access, this must be 1, and the default is 1.\nIf too many patients match the search criteria, we return a `TOO_MANY_MATCHES` error.\n","example":1,"in":"query","required":false,"schema":{"type":"integer","format":"int32"}},"Family":{"name":"family","description":"The patient's family name (surname).\n\nNot case sensitive. Max 35 characters.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n","examples":{"simple":{"value":"Smith","summary":"Matches Smythe if `_fuzzy-match` is specified."},"wildcarded":{"value":"Sm*t*","summary":"Wildcards must contain at least two characters, this matches Smith, Smythe"}},"in":"query","required":false,"schema":{"type":"string"}},"Given":{"name":"given","description":"The patient's given names, including their first and middle names.\n\nNot case sensitive. Max 35 characters.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nWildcard searches will match the start of the first given name and not subsequent given names, for example the given names \"Alan Michael\" can be searched with \"Ala*\" but not \"Mic*\".\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n\nA patient may have more than one given name, for example because they have a first name and a middle name.\nSpecify multiple given names by repeating this parameter.\nTo search for `Jane Anne Smith` use `given=Jane&given=Anne&family=Smith`.\n\nThe first name may be a [compound name](https://en.wikipedia.org/wiki/Given_name#Compound), for example `John Paul`.\nTo search for `John Paul James Smith` (where `John Paul` is the first name, `James` is the middle name, and `Smith` the family name) use `given=John%20Paul&given=James&family=Smith`.\n\nIt is not necessary to specify subsequent given names, and doing so may impact your search results if they are not recorded in the PDS.\n","example":"Jane","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}}},"Gender":{"name":"gender","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.","example":"female","in":"query","required":false,"schema":{"type":"string","enum":["male","female","other","unknown"],"example":"female"}},"Birthdate":{"name":"birthdate","in":"query","description":"Date of birth in the format `yyyy-mm-dd`. To specify a range, use `birthdate=geyyyy-mm-dd&birthdate=leyyyy-mm-dd`.","examples":{"simple":{"value":["eq2010-10-22"],"description":"Exact match date"},"rangege":{"value":["ge2010-10-22"],"description":"Greater than or equals match, which matches 2010-10-22 or 2010-10-23"},"rangele":{"value":["le2010-10-22"],"description":"Less than or equals match, which matches 2010-10-22 or 2010-10-21"}},"required":false,"schema":{"type":"array","items":{"type":"string"}}},"DeathDate":{"name":"death-date","in":"query","description":"Date of death in the format `yyyy-mm-dd`. To specify a range, use `death-date=geyyyy-mm-dd&death-date=leyyyy-mm-dd`.\n\nFor a fuzzy search, this is ignored for matching but included in the score calculation.\n","examples":{"simple":{"value":"eq2010-10-22","description":"Exact match date"},"rangege":{"value":"ge2010-10-22","description":"Greater than or equals match which matches 2010-10-22 or 2010-10-23"},"rangele":{"value":"le2010-10-22","description":"Less than or equals match, which matches 2010-10-22 or 2010-10-21"}},"required":false,"schema":{"type":"string","format":"date"}},"AddressPostalcode":{"name":"address-postalcode","description":"The postcode of any of the patient's known addresses.\n\nNot case sensitive.\nSpaces are ignored, for example `LS16AE` and `LS1 6AE` both match `LS1 6AE`.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n","examples":{"simple":{"value":"LS1 6AE","summary":"Spaces ignored, would match LS16AE"},"wildcarded":{"value":"LS1*","summary":"Matches 'LS16AE', 'LS1 6AE' and 'LS1 6AB'"}},"in":"query","required":false,"schema":{"type":"string"}},"AddressPostcode":{"name":"address-postcode","description":"**N.B. that address-postcode will be deprecated in the future, address-postalcode should be used instead. \nIf both address-postcode and address-postalcode are provided, an INVALID_SEARCH_DATA error will be returned.**\nThe postcode of any of the patient's known addresses.\n\nNot case sensitive.\nSpaces are ignored, for example `LS16AE` and `LS1 6AE` both match `LS1 6AE`.\nUse `*` as a wildcard but not in the first two characters and not in fuzzy search mode.\nMust be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding), for example a space must be represented by either `%20` or `+` and a wildcard must be encoded as `%2A`.\n","examples":{"simple":{"value":"LS1 6AE","summary":"Spaces ignored, would match LS16AE"},"wildcarded":{"value":"LS1*","summary":"Matches 'LS16AE', 'LS1 6AE' and 'LS1 6AB'"}},"in":"query","required":false,"schema":{"type":"string"}},"GeneralPractitioner":{"name":"general-practitioner","description":"The Organisation Data Service (ODS) code of the patient's registered GP practice.\n\nNot case sensitive.\nFor a fuzzy search, this is ignored for matching but included in the score calculation.\n","example":"Y12345","in":"query","required":false,"schema":{"type":"string"}},"ManagingOrganization":{"name":"managing-organization","description":"**This field is for internal-use only**.\n\nThe Organisation Data Service (ODS) code of the patient's current managing organization.\nNot case sensitive.\nFor a fuzzy search, this is ignored for matching but included in the score calculation.\n","example":"Y12345","in":"query","required":false,"schema":{"type":"string"}},"ETag":{"name":"etag","schema":{"type":"string","pattern":"^W/\"[0-9]+\"$","example":"W/\"2\""},"in":"header","description":"Record version identifier enclosed in quotes and preceded by 'W/'. For example, `W/\"2\"`.\n\nCorresponds to `meta.versionId` attribute in the patient resource body.\n\nWhen 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).\nYou must then pass the resource's version number in any update request (in the `If-Match` response header) made for the patient.\n"},"XCorrelationId":{"name":"x-correlation-id","schema":{"type":"string","example":"11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"},"in":"header","description":"The X-Correlation-ID from the request header, if supplied, mirrored back.\n"},"RetryAfter":{"name":"retry-after","description":"Time to wait before retrying your request in seconds","in":"header","schema":{"type":"string","example":"5"}},"EmailAddress":{"name":"email","description":"Email address\n","example":"jane.smith@example.com","in":"query","required":false,"schema":{"type":"string"}},"PhoneNumber":{"name":"phone","description":"Phone number\n","example":"01632960587","in":"query","required":false,"schema":{"type":"string"}},"SubscriberIdentifier":{"name":"subscriber:identifier","description":"The NHS number that identifies the holder/subscriber of the coverage.\n","examples":{"ehic_holder":{"value":9000000009,"summary":"Returns a bundle that contains a Coverage resource for the patient with NHS number 9733162868."},"no_ehic":{"value":9000000033,"summary":"Returns an empty bundle, alongside a meta object that can be used to apply an update to the patient's coverage."}},"in":"query","required":true,"schema":{"type":"string"}}},"schemas":{"Patient":{"type":"object","required":["id"],"additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"id":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"identifier":{"type":"array","description":"Identifier and system of identification used for this Patient.","maxItems":1,"items":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","description":"System identifier belongs to.","default":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"extension":{"type":"array","description":"FHIR extensions.","items":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}}}}}},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The NHS Digital assigned version of the patient resource.","example":"2"},"security":{"type":"array","description":"The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:\n* U - unrestricted. All available data is returned.\n* R - restricted. Any sensitive data around the patient's location, so `address`, `generalPractitioner` and `telecom`, are removed from the response.\n* REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.\n","maxItems":1,"items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the value set specification.","example":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality"},"code":{"type":"string","description":"Code defined by the system value set.","enum":["U","R","V","REDACTED"],"example":"U"},"display":{"type":"string","description":"Representation defined by the system.","enum":["unrestricted","restricted","redacted"],"example":"unrestricted"}}}}}},"name":{"type":"array","description":"List of names associated with the patient. This may not appear if the patient is tagged as `restricted` (also known as a sensitive patient). \n","minItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"multipleBirthInteger":{"type":"integer","minimum":1,"maximum":9,"description":"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.\n\nThere are two other valid values; `8` meaning `Not applicable` and `9` meaning `Not known`.\n","example":1},"deceasedDateTime":{"description":"The date and time in UTC on which a person died or is officially deemed to have died, if applicable and known.\n\nIt is a datetime in the format `yyyy-mm-ddTHH:MM:SS+00:00` or `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.\n","example":"2010-10-22T00:00:00+00:00","type":"string","format":"date-time","pattern":"^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T\\d{2}:\\d{2}:\\d{2}\\+00:00)$|^([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]))$"},"address":{"type":"array","description":"List of addresses associated with the patient.\n\nThese are fully populated on a retrieval or a successful update, only the `home` address is returned on a search.\nWhen a patient tagged as `restricted` is retrieved, all addresses are removed from the response.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient, like phone numbers or email addresses. A patient should only have one instance of each telecom system and use combination on their record at a time. For example, to add a new work email value to the record, the existing work email value should be replaced with the new value. When a patient tagged as `restricted` is retrieved, all contact points, like phone numbers or email addresses, are removed from the response.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"contact":{"type":"array","description":"A list of patient contacts. Only emergency contacts are returned and only emergency contacts should be added. Any other contacts should be added to the patients `Related Person`.\nPatients designate here any contact number they desire to be used in case of an emergency.\nNote, 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.\nWhen a patient tagged as `restricted` is retrieved, all contacts are removed from the response.\n","items":{"title":"Schema for a patient contact.","type":"object","additionalProperties":false,"required":["relationship","telecom"],"properties":{"id":{"type":"string","example":"C123"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"relationship":{"type":"array","description":"The contact relationship wrapper object that holds the details of the relationship to the patient.\n\nThis is only returned when an Emergency Contact number has been set on `telecom`. The only valid code is `C`, which means `Emergency Contact`.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}}},"telecom":{"type":"array","description":"List of Telecom objects on the contact only contains `system` and `value`.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}}}}},"generalPractitioner":{"type":"array","maxItems":1,"description":"General Practice (not practitioner) with which the patient is, or was, registered. Always contains zero or one general practitioner object.\nWhen a patient tagged as `restricted` is retrieved, the General Practice is removed from the response.\n","items":{"description":"General practice (not practitioner) with which the patient is or was registered.","type":"object","required":["identifier"],"properties":{"id":{"description":"Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.","type":"string","example":"254406A3"},"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}}},"managingOrganization":{"description":"The managing organization of a de-registered patient. This will not be returned when the reason for de-registration is death.","type":"object","required":["identifier"],"properties":{"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}},"extension":{"type":"array","description":"Wrapper array for the patient's pharmacies, death notification status, communication details, contact preferences and place of birth; these are all FHIR extensions.\nAlways 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.\nWhen a patient tagged as `restricted` is retrieved, the pharmacy and birth place extensions are removed from the response.\n","items":{"anyOf":[{"type":"object","description":"Wrapper object for the patient's nominated pharmacy. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-NominatedPharmacy FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy"]},"valueReference":{"type":"object","description":"Reference to a pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's nominated pharmacy organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the nominated pharmacy, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y12345"}}}}}}},{"type":"object","description":"Wrapper object for the patient's dispensing doctor. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-DispensingDoctor FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization"]},"valueReference":{"type":"object","description":"Reference to a GP practice pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's dispensing doctor organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the dispensing doctor, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y23456"}}}}}}},{"type":"object","description":"Wrapper object for the patient's medical appliance supplier. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-MedicalApplianceSupplier FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier"]},"valueReference":{"type":"object","description":"Reference to medical appliance supplier pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's medical appliance supplier organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the medical appliance supplier, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y34567"}}}}}}},{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for place of birth details. This will not be returned on a restricted patient.","required":["url","valueAddress"],"properties":{"url":{"type":"string","description":"Definition of place of birth extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","enum":["http://hl7.org/fhir/StructureDefinition/patient-birthPlace"]},"valueAddress":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string","description":"Town or city of birth.","example":"Manchester"},"district":{"type":"string","description":"County or metropolitan district of birth.","example":"Greater Manchester"},"country":{"type":"string","description":"A coded value for a patient's country of birth.\n\nFrom [ISO 3166-1](http://hl7.org/fhir/valueset-iso3166-1-3.html) plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.\n\nUK Internal Codes:\n* `1` - England\n* `2` - Scotland\n* `3` - Wales\n* `4` - Northern Ireland\n* `7` - Sark\n* `9` - Alderney\n* `10` - Channel Islands\n","example":"GBR"}}}}},{"type":"object","description":"An extension to carry the reason a PDS record has been removed from the Patient Demographic Service. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the removal from registration extension.","example":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","enum":["https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration"],"readOnly":true},"extension":{"type":"array","description":"An extension reason a PDS record has been removed from the Patient Demographic Service.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for removalFromRegistrationCode.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"To identify the removal reason code.","example":"removalFromRegistrationCode","enum":["removalFromRegistrationCode"],"readOnly":true},"valueCodeableConcept":{"type":"object","description":"PDS Removal Reason Exit Code","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one removal reason exit code object","items":{"type":"object","required":["system","code","display"],"properties":{"system":{"type":"string","format":"url","description":"URL of the Removal Reason Exit Code. Always uses the 'PDS-RemovalReasonExitCode' Code System.","example":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","readOnly":true},"code":{"type":"string","example":"SCT","enum":["DEA","EMB","SCT","NIT","TRA","ORR"],"description":"A CodeSystem that identifies the reason a PDS record has been removed:\n* `DEA` - Death\n* `EMB` - Embarkation\n* `SCT` - Transferred to Scotland\n* `NIT` - Transferred to Northern Ireland\n* `TRA` - Temporary resident not returned\n* `ORR` - Other reason\n"},"display":{"type":"string","description":"Display-friendly representation of the removal reason exit code.","example":"Transferred to Scotland"}}}}}}}},{"type":"object","description":"Wrapper object for removal from registration effective time.","required":["url","valuePeriod"],"properties":{"url":{"type":"string","description":"Key of this object. Always `effectiveTime`.","example":"effectiveTime","enum":["effectiveTime"],"readOnly":true},"valuePeriod":{"type":"object","description":"The effective time of removal of the Patient record from PDS.","required":["start"],"properties":{"start":{"type":"string","format":"date-time","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2020-01-01T00:00:00+00:00"},"end":{"type":"string","format":"date-time","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2021-12-31T00:00:00+00:00"}}}}}]}}}}]}}}},"PatientSearch":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"Bundle"},"type":{"type":"string","description":"FHIR Bundle Type.","default":"searchset"},"timestamp":{"type":"string","description":"Time the search was performed.","format":"datetime","example":"2019-12-25T12:00:00+00:00"},"total":{"type":"integer","description":"Number of resources returned in search.","example":1},"entry":{"type":"array","description":"A list of matched patients. Empty if none found. The patients are ordered by match score, best first. A maximum of 50 patients are returned.\n","items":{"type":"object","properties":{"fullUrl":{"type":"string","description":"Absolute URL of the resource described in this item.","example":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009"},"search":{"type":"object","properties":{"score":{"description":"Search score from 0.0 to 1.0.","type":"number","minimum":0,"maximum":1,"example":0.75}}},"resource":{"type":"object","additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"id":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"identifier":{"type":"array","description":"Identifier and system of identification used for this Patient.","maxItems":1,"items":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","description":"System identifier belongs to.","default":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"extension":{"type":"array","description":"FHIR extensions.","items":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}}}}}},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The NHS Digital assigned version of the patient resource.","example":"2"},"security":{"type":"array","description":"The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:\n* U - unrestricted. All available data is returned.\n* R - restricted. Any sensitive data around the patient's location, so `address`, `generalPractitioner` and `telecom`, are removed from the response.\n* REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.\n","maxItems":1,"items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the value set specification.","example":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality"},"code":{"type":"string","description":"Code defined by the system value set.","enum":["U","R","V","REDACTED"],"example":"U"},"display":{"type":"string","description":"Representation defined by the system.","enum":["unrestricted","restricted","redacted"],"example":"unrestricted"}}}}}},"name":{"type":"array","description":"List of names associated with the patient.\nThis is only fully populated on a retrieval or a successful update, only the `usual`, `nickname` and `temp` names are returned on a search. \n","minItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"multipleBirthInteger":{"type":"integer","minimum":1,"maximum":9,"description":"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.\n\nThere are two other valid values; `8` meaning `Not applicable` and `9` meaning `Not known`.\n","example":1},"deceasedDateTime":{"description":"The date and time in UTC on which a person died or is officially deemed to have died, if applicable and known.\n\nIt is a datetime in the format `yyyy-mm-ddTHH:MM:SS+00:00` or `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.\n","example":"2010-10-22T00:00:00+00:00","type":"string","format":"date-time","pattern":"^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T\\d{2}:\\d{2}:\\d{2}\\+00:00)$|^([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]))$"},"address":{"type":"array","description":"List of addresses associated with the patient.\n\nThis is only fully populated on a retrieval or a successful update, only the `home` address is returned on a search.\nWhen a patient tagged as `restricted` is retrieved, all addresses are removed from the response.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient; for example, phone numbers or email addresses.\nWhen a patient tagged as `restricted` is retrieved, all contact points are removed from the response.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"contact":{"type":"array","description":"A list of patient contacts. Only emergency contacts are returned. Any other contacts are returned on the patients `Related Person`.\nWhen a patient tagged as `restricted` is retrieved, all contacts are removed from the response.\n","items":{"title":"Schema for a patient contact.","type":"object","additionalProperties":false,"required":["relationship","telecom"],"properties":{"id":{"type":"string","example":"C123"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"relationship":{"type":"array","description":"The contact relationship wrapper object that holds the details of the relationship to the patient.\n\nThis is only returned when an Emergency Contact number has been set on `telecom`. The only valid code is `C`, which means `Emergency Contact`.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}}},"telecom":{"type":"array","description":"List of Telecom objects on the contact only contains `system` and `value`.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}}}}},"generalPractitioner":{"type":"array","maxItems":1,"description":"General Practice (not practitioner) with which the patient is, or was, registered. Always contains zero or one general practitioner object.\nWhen a patient tagged as `restricted` is retrieved, the General Practice is removed from the response.\n","items":{"description":"General practice (not practitioner) with which the patient is or was registered.","type":"object","required":["identifier"],"properties":{"id":{"description":"Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.","type":"string","example":"254406A3"},"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}}},"extension":{"type":"array","description":"Wrapper array for the patient's death notification status; this is a FHIR extension. Always contains zero or one death notification status object.\n","items":{"anyOf":[{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}}]}}}}}}}}},"RelatedPersonBundle":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"Bundle"},"type":{"type":"string","description":"FHIR Bundle Type.","default":"searchset"},"timestamp":{"type":"string","description":"Time the search was performed, including the year, month, date, time and timezone, in the format YYYY-MM-DDThh:mm:ss+hh:mm.","format":"datetime","example":"2019-12-25T12:00:00+00:00"},"total":{"type":"integer","description":"Number of resources returned in search.","example":1},"entry":{"type":"array","description":"A list of related people details attached to the patient. \n","items":{"type":"object","properties":{"fullUrl":{"type":"string","description":"Absolute URL of the resource described in this item.","example":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Patient/9000000009/RelatedPerson/507B7621"},"resource":{"type":"object","additionalProperties":false,"required":["patient","relationship"],"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"507B7621"},"resourceType":{"type":"string","description":"FHIR resource type.","default":"RelatedPerson"},"patient":{"type":"object","properties":{"identifier":{"type":"object","description":"Identifier and system of identification used for this Patient.\n\nThis 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.\n","properties":{"system":{"type":"string","default":"https://fhir.nhs.uk/Id/nhs-number","description":"URL for the Patient retrieval API.","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"]},"value":{"type":"string","description":"NHS number for the related person","example":"9000000009","pattern":"^\\d{10}$"}}}}},"active":{"type":"boolean","default":true},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"name":{"type":"array","description":"List containing zero or one name associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\nIf no `patient` reference is available `name` and `address` must be provided at the minimum.\n","maxItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"address":{"type":"array","description":"List containing zero or one address associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\nIf no `patient` reference is available `name` and `address` must be provided at the minimum.\n","maxItems":1,"items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List containing zero to five contact methods associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\n","maxItems":5,"items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"relationship":{"type":"array","description":"The relationship of the related person to the patient.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Coded values for three relationship types:\n* Role\n* Type\n* Next-of-Kin\n\nThe codes used can be found at:\n* http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype\n* https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole\n\nThe allowed values for `Role` are:\n* Agent - Agent of patient\n* Guardian - Guardian of patient\n* Personal - Personal relationship with the patient\n\nThe allowed values for `Type` are:\n* SPS - spouse\n* DOMPART - domestic partner\n* PRN - parent\n* PRNFOST - foster parent\n* STPPRN - step parent\n* CHILD - child\n* MTH - mother\n* FTH - father\n* SIS - sister\n* BRO - brother\n* FAMMEMB - family member\n* ONESELF - self\n* N - Next-of-Kin\n* U - Unknown\n* PolygamousPartner - Polygamous Partner of patient\n* Dependant - Dependant of patient\n* NonDependant - Non Dependant of patient\n* ProxyContact - Proxy Contact for patient\n* ProxyCommunication - Proxy Communication for patient\n* ProxyContactCommunication - Proxy Contact and Communication for patient\n* Carer - Carer of patient\n* Guardian - Guardian of patient\n* NotSpecified - Not Specified\n\nThe allowed values for `Next-of-Kin` are:\n* N - Next-of-Kin\n\n`Role` and `Type` are mandatory, so both should be present - however they both contain the `Guardian` code - so a single response is possible.\n\n`Next-of-Kin` is optional and will be absent from the response when the related person is not the Next-of-Kin.\n","minItems":1,"maxItems":3,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","format":"url","example":"https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole","enum":["http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype","https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole"]},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"Guardian"},"display":{"type":"string","description":"Human-friendly display representation defined by the system.","example":"Guardian of patient"}}}}}}},"extension":{"type":"array","description":"Wrapper array for copy correspondence, contact rank, contact preferences and communication details; these are all FHIR extensions. Always contains zero or one of each extension type.\n","items":{"anyOf":[{"type":"object","description":"Flag indicating if this person should be copied in on any contact with the Patient. This will only be returned if the value is true and the person should be copied in on correspondence, otherwise it will be omitted. \n","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator"]},"valueBoolean":{"type":"boolean","description":"Flag indicating if this person should be copied in on correspondence. This will only be returned if the value is `true` otherwise it will not be returned and can be assumed `false`","example":true}}},{"type":"object","description":"Rank indicating order in which contacts should be tried.","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank"]},"valuePositiveInt":{"type":"integer","minimum":1,"maximum":99,"description":"Rank expressed as positive integer (1 being the highest).","example":1}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}}]}}}}}}}}},"OperationOutcome":{"type":"object","description":"Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission.\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\n","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","default":"OperationOutcome"},"issue":{"type":"array","description":"List of issues that have occurred.","minItems":1,"items":{"type":"object","required":["severity","code"],"properties":{"severity":{"type":"string","enum":["fatal","error","warning","information"],"description":"Severity of the error.","example":"error"},"code":{"type":"string","description":"FHIR error code.","example":"invalid","enum":["invalid","structure","required","value","invariant","security","login","unknown","expired","forbidden","suppressed","processing","not-supported","duplicate","multiple-matches","not-found","deleted","too-long","code-invalid","extension","too-costly","business-rule","conflict","transient","lock-error","no-store","exception","timeout","incomplete","throttled","informational"]},"details":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"diagnostics":{"type":"string","description":"Additional diagnostic information about the issue. This information is subject to change.","example":"Invalid value - 2019-01 in field 'birthDate'"},"expression":{"type":"string","description":"FHIRPath of element(s) related to the error.","example":"Patient.name.given"}}}}}},"NhsNumber":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"NHSNumberVerificationStatus":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}},"NHSNumberVerificationStatus-2":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}},"Identifier":{"type":"array","description":"Identifier and system of identification used for this Patient.","maxItems":1,"items":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","description":"System identifier belongs to.","default":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"},"extension":{"type":"array","description":"FHIR extensions.","items":{"type":"object","description":"Status indicating if NHS number is present and verified.","properties":{"url":{"type":"string","description":"URL of the extension definition.","default":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberVerificationStatus"]},"valueCodeableConcept":{"type":"object","description":"NHS Number Verification Status Indicator.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-NHSNumberVerificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"01"},"display":{"type":"string","description":"Representation defined by the system.","example":"Number present and verified"}}}}}}}}}}}},"Meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The NHS Digital assigned version of the patient resource.","example":"2"},"security":{"type":"array","description":"The level of security on the patients record, which affects which fields are populated on retrieval. The possible responses are:\n* U - unrestricted. All available data is returned.\n* R - restricted. Any sensitive data around the patient's location, so `address`, `generalPractitioner` and `telecom`, are removed from the response.\n* REDACTED - redacted. The patient record has been marked as invalid, so the data should not be used. This code is never returned; you receive a 404, and appropriate error response, if an invalidated patient retrieval is attempted.\n","maxItems":1,"items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the value set specification.","example":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality"},"code":{"type":"string","description":"Code defined by the system value set.","enum":["U","R","V","REDACTED"],"example":"U"},"display":{"type":"string","description":"Representation defined by the system.","enum":["unrestricted","restricted","redacted"],"example":"unrestricted"}}}}}},"Period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"HumanName":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}},"Gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"BirthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"MultipleBirthOrder":{"type":"integer","minimum":1,"maximum":9,"description":"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.\n\nThere are two other valid values; `8` meaning `Not applicable` and `9` meaning `Not known`.\n","example":1},"DeceasedDateTime":{"description":"The date and time in UTC on which a person died or is officially deemed to have died, if applicable and known.\n\nIt is a datetime in the format `yyyy-mm-ddTHH:MM:SS+00:00` or `yyyy-mm-dd`. Due to data quality issues on a small number of patients `yyyy-mm` and `yyyy` format may also be returned.\n","example":"2010-10-22T00:00:00+00:00","type":"string","format":"date-time","pattern":"^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T\\d{2}:\\d{2}:\\d{2}\\+00:00)$|^([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]))$"},"PAFAddressKey":{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},"UPRNAddressKey":{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}},"Address":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}},"OtherContactSystem":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}},"ContactPoint":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}},"ContactRelationship":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}},"Contact":{"title":"Schema for a patient contact.","type":"object","additionalProperties":false,"required":["relationship","telecom"],"properties":{"id":{"type":"string","example":"C123"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"relationship":{"type":"array","description":"The contact relationship wrapper object that holds the details of the relationship to the patient.\n\nThis is only returned when an Emergency Contact number has been set on `telecom`. The only valid code is `C`, which means `Emergency Contact`.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one contact relationship.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","format":"url","default":"http://terminology.hl7.org/CodeSystem/v2-0131"},"code":{"type":"string","description":"Coded value for contact relationship.","example":"C"},"display":{"type":"string","description":"Display-friendly representation of the contact relationship code.","example":"Emergency Contact"}}}}}}},"telecom":{"type":"array","description":"List of Telecom objects on the contact only contains `system` and `value`.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}}}},"GeneralPractitionerReference":{"description":"General practice (not practitioner) with which the patient is or was registered.","type":"object","required":["identifier"],"properties":{"id":{"description":"Object identifier (OID) specific to the returned details - this should be return exactly the same in any update.","type":"string","example":"254406A3"},"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}},"DeathNotificationStatus":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}},"DeathNotificationStatus-2":{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}},"ErrorCode":{"type":"object","description":"Internal error code.","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.nhs.uk/R4/CodeSystem/Spine-ErrorOrWarningCode"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1"},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"INVALID_VALUE"},"display":{"type":"string","description":"Representation defined by the system.","example":"Provided value is invalid"}}}}}},"RegisteringAuthorityType":{"type":"object","description":"Registering Authority Type","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one registering authority type","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of the Registering Authority Type. Always uses the 'UKCore-RegisteringAuthorityType' Code System.","example":"https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType","enum":["https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType"]},"code":{"type":"string","description":"A CodeSystem that identifies the type of the registering authority.","example":"x","enum":["a","b","c","d","e","f","g","h","i","j","k","l","m","n","o","p","q","r","s","t","u","v","w","x","1"]},"display":{"type":"string","description":"Display-friendly representation of the registering authority type.","example":"NHAIS"}}}}}},"RegisteringAuthority":{"type":"object","description":"Definition of registering authority extension.","required":["url","extension"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-RegisteringAuthority FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority"]},"extension":{"type":"array","description":"Array containing exactly one registering authority type object, exactly one organization identifier object, and may include a person identifier object.","minItems":2,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for registering authority type code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `registeringAuthorityType`.","example":"registeringAuthorityType","enum":["registeringAuthorityType"]},"valueCodeableConcept":{"type":"object","description":"Registering Authority Type","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one registering authority type","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of the Registering Authority Type. Always uses the 'UKCore-RegisteringAuthorityType' Code System.","example":"https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType","enum":["https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType"]},"code":{"type":"string","description":"A CodeSystem that identifies the type of the registering authority.","example":"x","enum":["a","b","c","d","e","f","g","h","i","j","k","l","m","n","o","p","q","r","s","t","u","v","w","x","1"]},"display":{"type":"string","description":"Display-friendly representation of the registering authority type.","example":"NHAIS"}}}}}}}},{"type":"object","description":"Wrapper object for registering authority organization identifier.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `organisationIdentifier`.","example":"organisationIdentifier","enum":["organisationIdentifier"]},"valueString":{"type":"string","description":"Wrapper for the registering authority organization identifier.","minLength":2,"maxLength":15}}}]}}}},"Language":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}},"Communication":{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}},"BirthPlace":{"type":"object","description":"Wrapper object for place of birth details. This will not be returned on a restricted patient.","required":["url","valueAddress"],"properties":{"url":{"type":"string","description":"Definition of place of birth extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","enum":["http://hl7.org/fhir/StructureDefinition/patient-birthPlace"]},"valueAddress":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string","description":"Town or city of birth.","example":"Manchester"},"district":{"type":"string","description":"County or metropolitan district of birth.","example":"Greater Manchester"},"country":{"type":"string","description":"A coded value for a patient's country of birth.\n\nFrom [ISO 3166-1](http://hl7.org/fhir/valueset-iso3166-1-3.html) plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.\n\nUK Internal Codes:\n* `1` - England\n* `2` - Scotland\n* `3` - Wales\n* `4` - Northern Ireland\n* `7` - Sark\n* `9` - Alderney\n* `10` - Channel Islands\n","example":"GBR"}}}}},"BirthSex":{"type":"object","description":"Wrapper object for birth sex details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of birth sex extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-BirthSex","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-BirthSex"]}}},"CadavericDonor":{"type":"object","description":"Wrapper object for cadaveric donor details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of cadaveric donor extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor","enum":["http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor"]}}},"ContactPreference":{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},"EthnicCategory":{"type":"object","description":"Wrapper object for ethnic category details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of ethnic category extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory"]}}},"ResidentialStatus":{"type":"object","description":"Wrapper object for residential status details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of residential status extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ResidentialStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ResidentialStatus"]}}},"PatientInterpreterRequired":{"type":"object","description":"Wrapper object for patient interpreter required details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of patient interpreter required extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-interpreterRequired","enum":["http://hl7.org/fhir/StructureDefinition/patient-interpreterRequired"]}}},"NhsNumberUnavailableReason":{"type":"object","description":"Wrapper object for nhs number unavailable reason details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of nhs number unavailable reason extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberUnavailableReason","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberUnavailableReason"]}}},"PatientCreateRequest":{"description":"Request to create a record for a new patient","type":"object","required":["name","gender","birthDate","address","extension"],"additionalProperties":false,"properties":{"resourceType":{"type":"string","description":"FHIR resource type.","default":"Patient"},"name":{"type":"array","description":"List of names associated with the patient.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"gender":{"type":"string","description":"This is the gender that is recorded on official documents, for example a birth certificate or passport. For some people, the gender held in PDS might not match the gender they identify with.\n","enum":["male","female","other","unknown"],"example":"female"},"birthDate":{"description":"The date on which the patient was born or is officially deemed to have been born.\n\nIt 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. \n","example":"2010-10-22","type":"string","format":"date"},"address":{"type":"array","description":"List of addresses associated with the patient.\n","items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List of contact points for the patient, such as phone numbers or email addresses. A patient should only have one instance of each telecom system and use combination on their record at a time. For example, the patient request should not contain multiple work email values in this array.\n","items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"extension":{"type":"array","description":"Wrapper array for inclusion of the following extensions, some will not actually persist data to PDS at this time (labelled not persisted):\n* Registering Authority (required)\n* Communication\n* Contact Preference\n* Birth Place (not persisted)\n* Birth Sex (not persisted)\n* Cadaveric Donor (not persisted)\n* Death Notification Status (not persisted)\n* Ethnic Category (not persisted)\n* Residential Status (not persisted)\n* Patient Interpreter Required (not persisted)\n* NHS Number Unavailable Reason (not persisted)\n","items":{"anyOf":[{"type":"object","description":"Definition of registering authority extension.","required":["url","extension"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-RegisteringAuthority FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-RegisteringAuthority"]},"extension":{"type":"array","description":"Array containing exactly one registering authority type object, exactly one organization identifier object, and may include a person identifier object.","minItems":2,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for registering authority type code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `registeringAuthorityType`.","example":"registeringAuthorityType","enum":["registeringAuthorityType"]},"valueCodeableConcept":{"type":"object","description":"Registering Authority Type","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one registering authority type","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of the Registering Authority Type. Always uses the 'UKCore-RegisteringAuthorityType' Code System.","example":"https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType","enum":["https://fhir.nhs.uk/CodeSystem/UKCore-RegisteringAuthorityType"]},"code":{"type":"string","description":"A CodeSystem that identifies the type of the registering authority.","example":"x","enum":["a","b","c","d","e","f","g","h","i","j","k","l","m","n","o","p","q","r","s","t","u","v","w","x","1"]},"display":{"type":"string","description":"Display-friendly representation of the registering authority type.","example":"NHAIS"}}}}}}}},{"type":"object","description":"Wrapper object for registering authority organization identifier.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `organisationIdentifier`.","example":"organisationIdentifier","enum":["organisationIdentifier"]},"valueString":{"type":"string","description":"Wrapper for the registering authority organization identifier.","minLength":2,"maxLength":15}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}},{"type":"object","description":"Wrapper object for place of birth details. This will not be returned on a restricted patient.","required":["url","valueAddress"],"properties":{"url":{"type":"string","description":"Definition of place of birth extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-birthPlace","enum":["http://hl7.org/fhir/StructureDefinition/patient-birthPlace"]},"valueAddress":{"type":"object","additionalProperties":false,"properties":{"city":{"type":"string","description":"Town or city of birth.","example":"Manchester"},"district":{"type":"string","description":"County or metropolitan district of birth.","example":"Greater Manchester"},"country":{"type":"string","description":"A coded value for a patient's country of birth.\n\nFrom [ISO 3166-1](http://hl7.org/fhir/valueset-iso3166-1-3.html) plus codes from the UK Internal Code list which do not have entries in ISO 3166-1.\n\nUK Internal Codes:\n* `1` - England\n* `2` - Scotland\n* `3` - Wales\n* `4` - Northern Ireland\n* `7` - Sark\n* `9` - Alderney\n* `10` - Channel Islands\n","example":"GBR"}}}}},{"type":"object","description":"Wrapper object for birth sex details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of birth sex extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-BirthSex","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-BirthSex"]}}},{"type":"object","description":"Wrapper object for cadaveric donor details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of cadaveric donor extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor","enum":["http://hl7.org/fhir/StructureDefinition/patient-cadavericDonor"]}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for death notification details.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of death notification extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-DeathNotificationStatus"]},"extension":{"type":"array","description":"Array containing exactly one death notification status code object and exactly one effective date object.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for death notification status code.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `deathNotificationStatus`.","example":"deathNotificationStatus","enum":["deathNotificationStatus"]},"valueCodeableConcept":{"type":"object","description":"Death Notification Status.","properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-DeathNotificationStatus"},"version":{"type":"string","description":"Version of the coding system in use.","example":"1.0.0"},"code":{"type":"string","description":"Symbol, in syntax, defined by the system:\n* `1` - Informal - death notice received via an update from a local NHS Organisation such as GP or Trust\n* `2` - Formal - death notice received from Registrar of Deaths. Only these endpoints are allowed to add a Formal death:\n - National Back Office using the Demographic Spine Application (DSA)\n - Office of National Statistics (ONS)\n - Maternity sites\n* `U` - Removed. This is a possible response, but it cannot be used on an update because Spine will reject it\n","example":"2","enum":["1","2","U"]},"display":{"type":"string","description":"Representation defined by the system.","example":"Formal - death notice received from Registrar of Deaths","enum":["Informal - death notice received via an update from a local NHS Organisation such as GP or Trust","Formal - death notice received from Registrar of Deaths","Removed"]}}}}}}}},{"type":"object","description":"Wrapper object for death notification effective date.","required":["url","valueDateTime"],"properties":{"url":{"type":"string","description":"Key of this object. Always `systemEffectiveDate`.","example":"systemEffectiveDate","enum":["systemEffectiveDate"]},"valueDateTime":{"type":"string","description":"Date and time at which death notification status took effect.","format":"date-time","example":"2010-10-22T00:00:00+00:00"}}}]}}}},{"type":"object","description":"Wrapper object for ethnic category details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of ethnic category extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-EthnicCategory"]}}},{"type":"object","description":"Wrapper object for residential status details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of residential status extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ResidentialStatus","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ResidentialStatus"]}}},{"type":"object","description":"Wrapper object for patient interpreter required details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of patient interpreter required extension.","example":"http://hl7.org/fhir/StructureDefinition/patient-interpreterRequired","enum":["http://hl7.org/fhir/StructureDefinition/patient-interpreterRequired"]}}},{"type":"object","description":"Wrapper object for nhs number unavailable reason details. This is accepted in a create patient request body but will not be persisted to PDS.","required":["url"],"properties":{"url":{"type":"string","description":"Definition of nhs number unavailable reason extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberUnavailableReason","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSNumberUnavailableReason"]}}}]}}}},"ManagingOrganizationReference":{"description":"The managing organization of a de-registered patient. This will not be returned when the reason for de-registration is death.","type":"object","required":["identifier"],"properties":{"type":{"description":"Type of Reference being returned.","type":"string","example":"Organization"},"identifier":{"description":"Identifier and system of identification used for this Organisation.","type":"object","required":["value"],"properties":{"system":{"description":"URL for the Organisation Data Service - who are responsible for publishing codes that identify organisations and individuals across health and social care.","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"description":"Organisation code for the registered general practice, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","type":"string","pattern":"^[0-9A-Z]+$","example":"Y12345"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}}}}}},"NominatedPharmacy":{"type":"object","description":"Wrapper object for the patient's nominated pharmacy. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-NominatedPharmacy FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NominatedPharmacy"]},"valueReference":{"type":"object","description":"Reference to a pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's nominated pharmacy organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the nominated pharmacy, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y12345"}}}}}}},"DispensingDoctor":{"type":"object","description":"Wrapper object for the patient's dispensing doctor. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-DispensingDoctor FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-PreferredDispenserOrganization"]},"valueReference":{"type":"object","description":"Reference to a GP practice pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's dispensing doctor organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the dispensing doctor, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y23456"}}}}}}},"MedicalApplianceSupplier":{"type":"object","description":"Wrapper object for the patient's medical appliance supplier. This will only be populated on a retrieval and not a search.","required":["url","valueReference"],"properties":{"url":{"type":"string","description":"URL of specification of UKCore-MedicalApplianceSupplier FHIR extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-MedicalApplianceSupplier"]},"valueReference":{"type":"object","description":"Reference to medical appliance supplier pharmacy `Organization` resource.","required":["identifier"],"properties":{"identifier":{"type":"object","description":"Wrapper object for the patient's medical appliance supplier organisation code.","required":["value"],"properties":{"system":{"type":"string","description":"URL for the FHIR code system for the ODS organisation code.","default":"https://fhir.nhs.uk/Id/ods-organization-code"},"value":{"type":"string","description":"Organisation code for the medical appliance supplier, as held in the [Organisation Data Service](https://developer.nhs.uk/apis/ods/).","pattern":"^[A-Za-z0-9]{3,10}$","example":"Y34567"}}}}}}},"RemovalReasonExitCode":{"type":"object","description":"PDS Removal Reason Exit Code","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one removal reason exit code object","items":{"type":"object","required":["system","code","display"],"properties":{"system":{"type":"string","format":"url","description":"URL of the Removal Reason Exit Code. Always uses the 'PDS-RemovalReasonExitCode' Code System.","example":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","readOnly":true},"code":{"type":"string","example":"SCT","enum":["DEA","EMB","SCT","NIT","TRA","ORR"],"description":"A CodeSystem that identifies the reason a PDS record has been removed:\n* `DEA` - Death\n* `EMB` - Embarkation\n* `SCT` - Transferred to Scotland\n* `NIT` - Transferred to Northern Ireland\n* `TRA` - Temporary resident not returned\n* `ORR` - Other reason\n"},"display":{"type":"string","description":"Display-friendly representation of the removal reason exit code.","example":"Transferred to Scotland"}}}}}},"RemovalFromRegistration":{"type":"object","description":"An extension to carry the reason a PDS record has been removed from the Patient Demographic Service. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the removal from registration extension.","example":"https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration","enum":["https://fhir.nhs.uk/StructureDefinition/Extension-PDS-RemovalFromRegistration"],"readOnly":true},"extension":{"type":"array","description":"An extension reason a PDS record has been removed from the Patient Demographic Service.","minItems":1,"maxItems":2,"items":{"oneOf":[{"type":"object","description":"Wrapper object for removalFromRegistrationCode.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"To identify the removal reason code.","example":"removalFromRegistrationCode","enum":["removalFromRegistrationCode"],"readOnly":true},"valueCodeableConcept":{"type":"object","description":"PDS Removal Reason Exit Code","required":["coding"],"properties":{"coding":{"type":"array","description":"Array containing exactly one removal reason exit code object","items":{"type":"object","required":["system","code","display"],"properties":{"system":{"type":"string","format":"url","description":"URL of the Removal Reason Exit Code. Always uses the 'PDS-RemovalReasonExitCode' Code System.","example":"https://fhir.nhs.uk/CodeSystem/PDS-RemovalReasonExitCode","readOnly":true},"code":{"type":"string","example":"SCT","enum":["DEA","EMB","SCT","NIT","TRA","ORR"],"description":"A CodeSystem that identifies the reason a PDS record has been removed:\n* `DEA` - Death\n* `EMB` - Embarkation\n* `SCT` - Transferred to Scotland\n* `NIT` - Transferred to Northern Ireland\n* `TRA` - Temporary resident not returned\n* `ORR` - Other reason\n"},"display":{"type":"string","description":"Display-friendly representation of the removal reason exit code.","example":"Transferred to Scotland"}}}}}}}},{"type":"object","description":"Wrapper object for removal from registration effective time.","required":["url","valuePeriod"],"properties":{"url":{"type":"string","description":"Key of this object. Always `effectiveTime`.","example":"effectiveTime","enum":["effectiveTime"],"readOnly":true},"valuePeriod":{"type":"object","description":"The effective time of removal of the Patient record from PDS.","required":["start"],"properties":{"start":{"type":"string","format":"date-time","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2020-01-01T00:00:00+00:00"},"end":{"type":"string","format":"date-time","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2021-12-31T00:00:00+00:00"}}}}}]}}}},"JsonPatch":{"type":"array","items":{"type":"object","required":["op","path"],"properties":{"op":{"type":"string","enum":["remove","add","replace","test"]},"path":{"description":"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.","type":"string","format":"jsonpointer","externalDocs":{"description":"IETF RFC 6901 JavaScript Object Notation (JSON) Pointer.","url":"https://tools.ietf.org/html/rfc6901"}},"value":{"description":"The information to be added or replaced. Should not be included on a remove.","oneOf":[{"type":"string"},{"type":"integer"},{"type":"object"}]}}}},"PatientReference":{"type":"object","properties":{"identifier":{"type":"object","description":"Identifier and system of identification used for this Patient.\n\nThis 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.\n","properties":{"system":{"type":"string","default":"https://fhir.nhs.uk/Id/nhs-number","description":"URL for the Patient retrieval API.","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"]},"value":{"type":"string","description":"NHS number for the related person","example":"9000000009","pattern":"^\\d{10}$"}}}}},"Relationship":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Coded values for three relationship types:\n* Role\n* Type\n* Next-of-Kin\n\nThe codes used can be found at:\n* http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype\n* https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole\n\nThe allowed values for `Role` are:\n* Agent - Agent of patient\n* Guardian - Guardian of patient\n* Personal - Personal relationship with the patient\n\nThe allowed values for `Type` are:\n* SPS - spouse\n* DOMPART - domestic partner\n* PRN - parent\n* PRNFOST - foster parent\n* STPPRN - step parent\n* CHILD - child\n* MTH - mother\n* FTH - father\n* SIS - sister\n* BRO - brother\n* FAMMEMB - family member\n* ONESELF - self\n* N - Next-of-Kin\n* U - Unknown\n* PolygamousPartner - Polygamous Partner of patient\n* Dependant - Dependant of patient\n* NonDependant - Non Dependant of patient\n* ProxyContact - Proxy Contact for patient\n* ProxyCommunication - Proxy Communication for patient\n* ProxyContactCommunication - Proxy Contact and Communication for patient\n* Carer - Carer of patient\n* Guardian - Guardian of patient\n* NotSpecified - Not Specified\n\nThe allowed values for `Next-of-Kin` are:\n* N - Next-of-Kin\n\n`Role` and `Type` are mandatory, so both should be present - however they both contain the `Guardian` code - so a single response is possible.\n\n`Next-of-Kin` is optional and will be absent from the response when the related person is not the Next-of-Kin.\n","minItems":1,"maxItems":3,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","format":"url","example":"https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole","enum":["http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype","https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole"]},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"Guardian"},"display":{"type":"string","description":"Human-friendly display representation defined by the system.","example":"Guardian of patient"}}}}}},"CopyCorrespondence":{"type":"object","description":"Flag indicating if this person should be copied in on any contact with the Patient. This will only be returned if the value is true and the person should be copied in on correspondence, otherwise it will be omitted. \n","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator"]},"valueBoolean":{"type":"boolean","description":"Flag indicating if this person should be copied in on correspondence. This will only be returned if the value is `true` otherwise it will not be returned and can be assumed `false`","example":true}}},"ContactRank":{"type":"object","description":"Rank indicating order in which contacts should be tried.","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank"]},"valuePositiveInt":{"type":"integer","minimum":1,"maximum":99,"description":"Rank expressed as positive integer (1 being the highest).","example":1}}},"RelatedPerson":{"type":"object","additionalProperties":false,"required":["patient","relationship"],"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"507B7621"},"resourceType":{"type":"string","description":"FHIR resource type.","default":"RelatedPerson"},"patient":{"type":"object","properties":{"identifier":{"type":"object","description":"Identifier and system of identification used for this Patient.\n\nThis 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.\n","properties":{"system":{"type":"string","default":"https://fhir.nhs.uk/Id/nhs-number","description":"URL for the Patient retrieval API.","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"]},"value":{"type":"string","description":"NHS number for the related person","example":"9000000009","pattern":"^\\d{10}$"}}}}},"active":{"type":"boolean","default":true},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"name":{"type":"array","description":"List containing zero or one name associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\nIf no `patient` reference is available `name` and `address` must be provided at the minimum.\n","maxItems":1,"items":{"type":"object","required":["use","family"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Unique object identifier for this name.","example":"123"},"use":{"type":"string","description":"How this name should be used.\n* usual - Known as, conventional or the one patient normally uses. A patient always has a usual name.\n* temp - An alias or temporary name. This may also be used for temporary names assigned at birth or in emergency situations.\n* nickname - A name that the patient prefers to be addressed by, but is not part of their usual name.\n* old - This name is no longer in use (or was never correct, but retained for records).\n* 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.\n\nThe following use codes are included in the [name-use](https://www.hl7.org/fhir/valueset-name-use.html) value set, but should not be used and is not be returned as part of a retrieval.\n* official - The formal name as registered in an official (government) registry, but which name might not be commonly used. May be called \"legal name\".\n* anonymous - Anonymous assigned name, alias, or pseudonym (used to protect a person's identity for privacy reasons).\n","enum":["usual","temp","nickname","old","maiden"],"example":"usual"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"given":{"type":"array","maxItems":5,"description":"Given names, including any middle names.\n\nEach name(s) should be a separate item in the list. The first given name may include multiple names, separated by a space.\nSubsequent names must be broken down into list items. For example, the input `[Jane Marie Anne, Jo Adele]` returns `[Jane Marie Anne, Jo, Adele]`.\n","example":["Jane Marie Anne","Jo","Adele"],"items":{"type":"string","maxLength":35,"example":"Jane"}},"family":{"type":"string","maxLength":35,"description":"Family name (often called Surname).","example":"Smith"},"prefix":{"type":"array","description":"Name prefixes, titles, and prenominals.","example":["Mrs"],"items":{"type":"string","example":"Mrs"}},"suffix":{"type":"array","description":"Name suffices and postnominals.","example":["MBE","PhD"],"items":{"type":"string","example":"MBE"}}}}},"address":{"type":"array","description":"List containing zero or one address associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\nIf no `patient` reference is available `name` and `address` must be provided at the minimum.\n","maxItems":1,"items":{"type":"object","description":"An address associated with the patient.","required":["use"],"properties":{"id":{"type":"string","description":"Unique system identifier for this address.","example":"456"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"use":{"type":"string","description":"Purpose of this address:\n * `home` - the home address is the patient's normal residence. Home address is also known as usual, main, registered, current or permanent address\n * `temp` - a temporary address is an address used for a set period of time, but where the patient's home, permanent address remains unchanged\n * `billing` - an address used for correspondence purposes only\n * `work` - an office address. This can be returned due to legacy data but cannot be added or replaced on update\n\n A patient should have no more than one current `temp` and/or `billing` address.\n 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.\n 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).\n\n 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.\n 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.\n When sending correspondence to a patient:\n *\ta 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.\n *\tif 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.\n * if there is no valid, current `billing` and/or `temp` address, the `home` address must be used.\n","enum":["home","work","temp","billing"],"example":"home"},"text":{"type":"string","description":"Where a `temp` address is provided a descriptor text must be sent. The list of allowed values are:\n* `Second Home` - a patient's second home\n* `Student Accommodation` - a patient's place of residence while at university\n* `Respite Care Address` - where the patient resides during respite care\n* `Temporary Residence Address` - where the patient resides for a specific period of time\n* `Convalescence Home` - the address for a patient during a period of recovery\n* `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\n* `Holiday Home` - the address for a patient during a holiday\n\nIn rare circumstances, an address may be returned with a value outside of this list.\n\nA patient can also register temporarily at a GP practice using a temporary address. Temporary GP registration information does not appear on the PDS, but the address used for it may.\n","enum":["Second Home","Student Accommodation","Respite Care Address","Temporary Residence Address","Convalescence Home","Mobile Home","Holiday Home"],"example":"Student Accommodation"},"line":{"type":"array","description":"All lines of the address except the postal code.\n\nSystems must apply the following formatting convention when adding or replacing addresses lines:\n* line 1 - premises ID and/or house name, e.g. `Flat 1` or `The Old Schoolhouse`\n* line 2 - house number, dependent thoroughfare name and descriptor (if present), thoroughfare name and descriptor, e.g. `23 Mill Lane`\n* line 3 - dependent locality/village, locality (if present), e.g. `Boxgrove`\n* line 4 - post town, e.g. `Leeds`\n* line 5 - county (if present), e.g. `West Yorkshire`\n\nIf any of the lines are blank, they are not returned due to FHIR conformance constraints.\n","maxItems":5,"items":{"type":"string"},"example":["1 Trevelyan Square","Boar Lane","City Centre","Leeds","West Yorkshire"]},"postalCode":{"type":"string","description":"Postal code of the address.","example":"LS1 6AE"},"extension":{"type":"array","description":"List of address keys formatted as a FHIR extension. This can include up to one Unique Property Reference Number (UPRN), and up to one Postal Address File (PAF) key. If no keys for the address are known, the array will be empty. Otherwise it will be a list of objects which specify the value of the address key and the code system for it","items":{"anyOf":[{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'PAF'.","enum":["PAF"],"example":"PAF"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in PAF format. An 8 digit number including leading zeroes, formatted as a string.","minLength":8,"maxLength":8,"pattern":"^[0-9]{8}$","example":"12345678"}}}]}}}},{"type":"object","description":"Unique identifier for an address.","properties":{"url":{"type":"string","description":"URL of specification of the AddressKey extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-AddressKey"]},"extension":{"type":"array","description":"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.","minItems":2,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Coding system of the address key.","required":["url","valueCoding"],"properties":{"url":{"type":"string","description":"Always 'type'.","example":"type"},"valueCoding":{"type":"object","description":"URL of specification of address key format.","required":["system","code"],"properties":{"system":{"type":"string","description":"URL of Code System that describes available Address Key formats.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-AddressKeyType"},"code":{"type":"string","description":"Address Key system. Always 'UPRN'.","enum":["UPRN"],"example":"UPRN"}}}}},{"type":"object","description":"Value of the address key.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Always 'value'.","example":"value"},"valueString":{"type":"string","description":"Address key in UPRN format. A number containing from 1 up to 12 digits.","minLength":1,"maxLength":12,"pattern":"^[0-9]{1,12}$","example":"123456789012"}}}]}}}}]}}}}},"telecom":{"type":"array","description":"List containing zero to five contact methods associated with the related person.\nThis is an optional field as there may be a `patient` reference which can be used to retrieve any details about the related person.\n","maxItems":5,"items":{"type":"object","required":["system","value"],"properties":{"id":{"type":"string","description":"Unique object identifier for this contact point.","example":"789"},"period":{"type":"object","description":"Business effective period when data item was, is, or will be in use.\n","required":["start"],"properties":{"start":{"type":"string","format":"date","description":"Start date of time period, if known, in format `yyyy-mm-dd`. Can be a future date.","example":"2024-01-01"},"end":{"type":"string","format":"date","description":"End date of time period, if known and if not ongoing, in format `yyyy-mm-dd`. Can be a future date.","example":"2025-12-31"}}},"system":{"description":"Means of communication, such as phone or email.","type":"string","enum":["phone","fax","email","other"],"example":"phone"},"value":{"description":"Phone number, email address, or other identifier for use with contact system.","type":"string","example":"01632960587"},"use":{"type":"string","description":"Location associated with communication system.","enum":["home","work","temp","mobile"],"example":"home"},"extension":{"type":"array","maxItems":1,"description":"Extension that is returned when the communication type is `textphone`. The only code returned is `textphone`, which means `Minicom (Textphone)`.\n\nThe `system` is `other` when the extension is included.\n","items":{"type":"object","description":"Wrapped object for other contact system details.","properties":{"url":{"type":"string","description":"Definition of other contact system extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-OtherContactSystem"]},"valueCoding":{"type":"object","description":"URL of specification of other contact systems.","properties":{"system":{"type":"string","description":"URL of Code System that describes available contact relationships.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-OtherContactSystem"},"code":{"type":"string","description":"Coded value for the other contact system in place.","example":"textphone"},"display":{"description":"Display-friendly representation of the other contact system code.","type":"string","example":"Minicom (Textphone)"}}}}}}}}},"relationship":{"type":"array","description":"The relationship of the related person to the patient.\n","minItems":1,"maxItems":1,"items":{"type":"object","required":["coding"],"properties":{"coding":{"type":"array","description":"Coded values for three relationship types:\n* Role\n* Type\n* Next-of-Kin\n\nThe codes used can be found at:\n* http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype\n* https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole\n\nThe allowed values for `Role` are:\n* Agent - Agent of patient\n* Guardian - Guardian of patient\n* Personal - Personal relationship with the patient\n\nThe allowed values for `Type` are:\n* SPS - spouse\n* DOMPART - domestic partner\n* PRN - parent\n* PRNFOST - foster parent\n* STPPRN - step parent\n* CHILD - child\n* MTH - mother\n* FTH - father\n* SIS - sister\n* BRO - brother\n* FAMMEMB - family member\n* ONESELF - self\n* N - Next-of-Kin\n* U - Unknown\n* PolygamousPartner - Polygamous Partner of patient\n* Dependant - Dependant of patient\n* NonDependant - Non Dependant of patient\n* ProxyContact - Proxy Contact for patient\n* ProxyCommunication - Proxy Communication for patient\n* ProxyContactCommunication - Proxy Contact and Communication for patient\n* Carer - Carer of patient\n* Guardian - Guardian of patient\n* NotSpecified - Not Specified\n\nThe allowed values for `Next-of-Kin` are:\n* N - Next-of-Kin\n\n`Role` and `Type` are mandatory, so both should be present - however they both contain the `Guardian` code - so a single response is possible.\n\n`Next-of-Kin` is optional and will be absent from the response when the related person is not the Next-of-Kin.\n","minItems":1,"maxItems":3,"items":{"type":"object","required":["system","code"],"properties":{"system":{"type":"string","description":"URI of the coding system specification.","format":"url","example":"https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole","enum":["http://hl7.org/fhir/ValueSet/relatedperson-relationshiptype","https://fhir.nhs.uk/R4/CodeSystem/UKCore-AdditionalRelatedPersonRole"]},"code":{"type":"string","description":"Symbol in syntax defined by the system.","example":"Guardian"},"display":{"type":"string","description":"Human-friendly display representation defined by the system.","example":"Guardian of patient"}}}}}}},"extension":{"type":"array","description":"Wrapper array for copy correspondence, contact rank, contact preferences and communication details; these are all FHIR extensions. Always contains zero or one of each extension type.\n","items":{"anyOf":[{"type":"object","description":"Flag indicating if this person should be copied in on any contact with the Patient. This will only be returned if the value is true and the person should be copied in on correspondence, otherwise it will be omitted. \n","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-CopyCorrespondenceIndicator"]},"valueBoolean":{"type":"boolean","description":"Flag indicating if this person should be copied in on correspondence. This will only be returned if the value is `true` otherwise it will not be returned and can be assumed `false`","example":true}}},{"type":"object","description":"Rank indicating order in which contacts should be tried.","properties":{"url":{"type":"string","format":"url","description":"URL to FHIR Extension Specification.","default":"https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank","enum":["https://fhir.nhs.uk/R4/StructureDefinition/Extension-UKCore-ContactRank"]},"valuePositiveInt":{"type":"integer","minimum":1,"maximum":99,"description":"Rank expressed as positive integer (1 being the highest).","example":1}}},{"type":"object","description":"Wrapper object for preferred contact details; the written communication format, preferred contact time and method. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of the contact preference extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-ContactPreference"]},"extension":{"description":"Wrapper array containing zero or one preferred contact method, zero or one preferred written communication format; and zero or one preferred contact time.","type":"array","maxItems":3,"items":{"oneOf":[{"type":"object","description":"Wrapper object for preferred written communication format.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredWrittenCommunicationFormat`.","example":"PreferredWrittenCommunicationFormat"},"valueCodeableConcept":{"type":"object","description":"Preferred Written Communication Format.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred written communication extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredWrittenCommunicationFormat"]},"code":{"type":"string","description":"A code to identify the preferred written communication format of a patient, contact or related person.\n* 11 - Large print\n* 12 - Braille\n* 13 - Audio tape\n","example":"12"},"display":{"type":"string","description":"Display-friendly representation of the preferred written communication format code.","example":"Braille"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact method.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactMethod`.","example":"PreferredContactMethod","enum":["PreferredContactMethod"]},"valueCodeableConcept":{"type":"object","description":"Preferred Contact Method.","required":["coding"],"properties":{"coding":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","format":"url","description":"Definition of the preferred contact method extension.","default":"https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod","enum":["https://fhir.hl7.org.uk/CodeSystem/UKCore-PreferredContactMethod"]},"code":{"type":"string","description":"A code to identify to identify the preferred contact method of a patient, contact or related person.\n* 1\t- Letter\n* 2\t- Visit\n* 3\t- Telephone\n* 4\t- E-mail\n* 5\t- Minicom (Textphone)\n* 6\t- Telephone contact via proxy\n* 7\t- Sign language\n* 8\t- No Telephone contact\n","example":"1"},"display":{"type":"string","description":"Display-friendly representation of the preferred contact method code.","example":"Letter"}}}}}}}},{"type":"object","description":"Wrapper object for preferred contact times.","required":["url","valueString"],"properties":{"url":{"type":"string","description":"Key of this object. Always `PreferredContactTimes`.","example":"PreferredContactTimes","enum":["PreferredContactTimes"]},"valueString":{"type":"string","maximum":40,"description":"A free-text description about the preferred contact times.","example":"Not after 7pm"}}}]}}}},{"type":"object","description":"Wrapper object for communication details. This will only be populated on a retrieval and not a search.","required":["url","extension"],"properties":{"url":{"type":"string","description":"Definition of communication extension.","example":"https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication","enum":["https://fhir.hl7.org.uk/StructureDefinition/Extension-UKCore-NHSCommunication"]},"extension":{"type":"array","description":"Definition of communication extension.\n\nThe array must have one item, a valueCodeableConcept for the language and can optionally include a valueBoolean for if an interpreter is required.","minItems":1,"maxItems":2,"items":{"anyOf":[{"type":"object","description":"Wrapper object for communication language.","required":["url","valueCodeableConcept"],"properties":{"url":{"type":"string","description":"Key of this object. Always `language`.","example":"language","enum":["language"]},"valueCodeableConcept":{"type":"object","description":"Human language.","required":["coding"],"properties":{"coding":{"type":"array","description":"Exactly one language code.","minItems":1,"maxItems":1,"items":{"type":"object","required":["code"],"properties":{"system":{"type":"string","description":"URL of the Language Code System. Always uses the 'UKCore-HumanLanguage' Code System.","example":"https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage"},"version":{"type":"string","description":"Version of the language code system.","example":"1.0.0"},"code":{"type":"string","description":"Language code based on [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) standard plus extensions for braille, makaton and sign languages, which are:\n* `q1` - Braille\n* `q2` - American Sign Language\n* `q3` - Australian Sign Language\n* `q4` - British Sign Language\n* `q5` - Makaton\nAll valid codes combined can be found at https://fhir.hl7.org.uk/CodeSystem/UKCore-HumanLanguage.\n","example":"fr"},"display":{"type":"string","description":"Even though the [code list](\"https://simplifier.net/packages/fhir.r4.ukcore.stu3.currentbuild/0.0.3-pre-release/files/1950414\") contains a value for English (en), preferred language must not contain this value.","example":"French"}}}}}}}},{"type":"object","description":"Wrapper object for whether an interpreter is required.","required":["url","valueBoolean"],"properties":{"url":{"type":"string","description":"Key of this object. Always `interpreterRequired`.","example":"interpreterRequired","enum":["interpreterRequired"]},"valueBoolean":{"type":"boolean","description":"Whether an interpreter is required.","example":true}}}]}}}}]}}}},"CountryCode":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["system","value"],"properties":{"system":{"type":"string","enum":["urn:iso:std:iso:3166"],"example":"urn:iso:std:iso:3166"},"value":{"type":"string","description":"Three-letter country code that identifies the country from which the Coverage originates.","example":"FRA","pattern":"^[A-Z]{3}$"}}},"display":{"type":"string","description":"Display-friendly representation of the country code.","readOnly":true,"example":"France"}}},"Coverage":{"description":"Insurance or medical plan or a payment agreement","type":"object","required":["status","beneficiary","payor","subscriber","identifier","period"],"properties":{"resourceType":{"type":"string","enum":["Coverage"],"example":"Coverage"},"status":{"type":"string","description":"The status of the resource instance.","enum":["active"],"example":"active"},"subscriber":{"type":"object","description":"Subscriber and patient covered by the policy. For EHIC, this is the patient's NHS number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"],"example":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"}}}}},"identifier":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["value","assigner"],"properties":{"value":{"type":"string","description":"The primary identifier of the insurer. For EHIC, this is the identification number of the card.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"29401395498043123948"},"assigner":{"description":"Identifier for the country that the coverage is from, in the format of the [International Organization for Standardization (ISO) three digital letter combination](https://www.gov.uk/government/publications/iso-country-codes--2) (ISO alpha-3). For EHIC, this is the country of issue.","type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["system","value"],"properties":{"system":{"type":"string","enum":["urn:iso:std:iso:3166"],"example":"urn:iso:std:iso:3166"},"value":{"type":"string","description":"Three-letter country code that identifies the country from which the Coverage originates.","example":"FRA","pattern":"^[A-Z]{3}$"}}},"display":{"type":"string","description":"Display-friendly representation of the country code.","readOnly":true,"example":"France"}}}}}},"payor":{"type":"array","description":"Issuer of the policy. For EHIC, this is the identification number of the institution.","minItems":1,"maxItems":1,"items":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The value that is unique","minLength":1,"maxLength":30,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,30}$","example":"92847ADGJL"}}}}}},"beneficiary":{"type":"object","description":"Plan beneficiary. For EHIC, this is the personal identification number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The personal ID number identifying the beneficiary.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"178705ABC"}}}}},"period":{"type":"object","description":"Time period when coverage is valid. For EHIC, this is the expiry date.","required":["end"],"properties":{"end":{"type":"string","format":"date","description":"End date of time period, if known, in format `yyyy-mm-dd`. Must be less than 150 years in the past. Must be less than 150 years in the future.","example":"2030-12-31"}}}}},"CoverageSearch":{"type":"object","properties":{"resourceType":{"type":"string","description":"FHIR Resource Type.","enum":["Bundle"],"default":"Bundle"},"type":{"type":"string","description":"FHIR Bundle Type.","enum":["searchset"],"default":"searchset"},"timestamp":{"type":"string","description":"Time the search was performed.","format":"datetime","example":"2019-12-25T12:00:00+00:00"},"total":{"type":"integer","description":"Number of resources returned in search.","minimum":0,"maximum":1,"example":1},"meta":{"type":"object","description":"Metadata about this resource.","properties":{"versionId":{"type":"string","description":"The current version number of the coverage details.","pattern":"^\\d+$","example":"2"}}},"entry":{"type":"array","description":"A list of matched coverages. Empty if none found.\n","items":{"type":"object","properties":{"fullUrl":{"type":"string","example":"https://api.service.nhs.uk/personal-demographics/FHIR/R4/Coverage?subscriber:identifier=9000000009"},"resource":{"description":"Insurance or medical plan or a payment agreement","type":"object","required":["status","beneficiary","payor","subscriber","identifier","period"],"properties":{"resourceType":{"type":"string","enum":["Coverage"],"example":"Coverage"},"status":{"type":"string","description":"The status of the resource instance.","enum":["active"],"example":"active"},"subscriber":{"type":"object","description":"Subscriber and patient covered by the policy. For EHIC, this is the patient's NHS number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"system":{"type":"string","format":"url","enum":["https://fhir.nhs.uk/Id/nhs-number"],"example":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"description":"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](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).","type":"string","pattern":"^\\d{10}$","example":"9000000009"}}}}},"identifier":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["value","assigner"],"properties":{"value":{"type":"string","description":"The primary identifier of the insurer. For EHIC, this is the identification number of the card.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"29401395498043123948"},"assigner":{"description":"Identifier for the country that the coverage is from, in the format of the [International Organization for Standardization (ISO) three digital letter combination](https://www.gov.uk/government/publications/iso-country-codes--2) (ISO alpha-3). For EHIC, this is the country of issue.","type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["system","value"],"properties":{"system":{"type":"string","enum":["urn:iso:std:iso:3166"],"example":"urn:iso:std:iso:3166"},"value":{"type":"string","description":"Three-letter country code that identifies the country from which the Coverage originates.","example":"FRA","pattern":"^[A-Z]{3}$"}}},"display":{"type":"string","description":"Display-friendly representation of the country code.","readOnly":true,"example":"France"}}}}}},"payor":{"type":"array","description":"Issuer of the policy. For EHIC, this is the identification number of the institution.","minItems":1,"maxItems":1,"items":{"type":"object","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The value that is unique","minLength":1,"maxLength":30,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,30}$","example":"92847ADGJL"}}}}}},"beneficiary":{"type":"object","description":"Plan beneficiary. For EHIC, this is the personal identification number.","required":["identifier"],"properties":{"identifier":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"The personal ID number identifying the beneficiary.","minLength":1,"maxLength":25,"pattern":"^[a-zA-Z0-9\\-,/:'. ]{1,25}$","example":"178705ABC"}}}}},"period":{"type":"object","description":"Time period when coverage is valid. For EHIC, this is the expiry date.","required":["end"],"properties":{"end":{"type":"string","format":"date","description":"End date of time period, if known, in format `yyyy-mm-dd`. Must be less than 150 years in the past. Must be less than 150 years in the future.","example":"2030-12-31"}}}}}}}}}}},"examples":{"OperationOutcome":{"summary":"OperationOutcome example","value":{"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"}]}}]}}}}}