Create or update patient

create-or-update-patient Message


In development. API spec subject to change.


This message allows a System to:

  • Create or update the demographics of a single patient

  • Trigger an email invitation to that patient


When updating fields, the following business logic is applied:

    • All textual values will have leading and trailing whitespace removed before being stored

    • Any textual value which exceeds the maximum database field length will be truncated, and a warning returned in the response

    • Empty values are not permitted in FHIR. Any attribute of the Patient either not provided, or else not supported by this Message, will not be modified. If the caller wishes to explicitly delete the value stored for a given field, they must provide the data absent reason extension. PKB will not store or process the specific reason provided, but will use the presence of the extension as an indicator that the value should be deleted. This is comparable to the HL7 Null Value in the HL7 v2 API specifications. The caller should particularly aware of this behaviour when updating compound values, such as the patient’s name and address.

Any unsupported fields will be silently ignored by PKB.


  1. Validate mandatory data

    1. Standard Message identifier validation and duplicate detection will be applied. See the $process-message specification for more information.

      1. ODS check. Return an error if any of the following conditions are not true:

      2. an ODS code has been provided in Patient.meta.tag

          1. system = “” (case sensitive)

          2. code = <the ODS code>

      3. this matches the ODS code of an existing PKB organisation

      4. that organisation has granted the sending client authorisation to interact with the FHIR API on their behalf

      5. Patient identifier check. Return an error if any of the following conditions are not true:

      6. An NHS number has been provided

          1. system = "" (case sensitive)

          2. value = <the NHS number>

      1. The status of the NHS number has been provided, and is verified

          1. extension.url = “” (case sensitive)

          2. extension.valueCodeableConcept.coding[0].system = “” (case sensitive)

        1. extension.valueCodeableConcept.coding[0].code= “01”

    1. Return an error if a given name is not present

    2. Return an error if a family name is not present

    3. Create or update the patient. Search for the patient, based on their identifier. This will search across the entire server, and will not be limited to records that the caller has access to.

    4. If patient not found: create a new medical record in the default team of the PKB organisation for the matching ODS code.

      1. Else: Update the demographic details with those provided in the message.

  1. Create or update the consent record.

    1. If there is no consent record between the patient and the default team of the PKB organisation for the matching ODS code:

      1. If the decryption key to the medical record is available to the org: create a new consent record. The discharged marker will be false, and the team should be granted their default privacy labels.

      2. Else: no action.

    2. Else:

      1. If the discharged marker on the existing consent record is true: set it to false

      2. Else: no action; the patient is already admitted to the team.

  1. Email invitations.

    1. If the patient is not yet registered, an invitation to register will be sent to each of their email addresses, providing that the decryption key was available and they have a date of birth stored on their record.

    2. If the patient is registered, an email will be sent to each unconfirmed email address asking them to confirm the contact.

  1. Respond. A response, as defined below, is sent to the caller's $process-message endpoint.