Developer documentation‎ > ‎FHIR® REST API‎ > ‎Roadmap‎ > ‎Messages‎ > ‎

Create or update patient


create-or-update-patient Message

https://www.hl7.org/fhir/STU3/messaging.html

Status

In development. API spec subject to change.

Overview

This message allows a System to:
  • Create or update the demographics of a single patient
  • Trigger an email invitation to that patient

Processing

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.
Workflow
  1. Validate mandatory data
    1. Standard Message identifier validation and duplicate detection will be applied. See the $process-message specification for more information.
    2. ODS check. Return an error if any of the following conditions are not true:
      1. an ODS code has been provided in Patient.meta.tag
        1. system = “https://fhir.nhs.uk/Id/ODS-Code” (case sensitive)
        2. code = <the ODS code>
      2. this matches the ODS code of an existing PKB organisation
      3. that organisation has granted the sending client authorisation to interact with the FHIR API on their behalf
    3. Patient identifier check. Return an error if any of the following conditions are not true:
      1. An NHS number has been provided
        1. system = "https://fhir.nhs.uk/Id/nhs-number" (case sensitive)
        2. value = <the NHS number>
      2. The status of the NHS number has been provided, and is verified
        1. extension.url = “ https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1” (case sensitive)
        2. extension.valueCodeableConcept.coding[0].system = “https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1” (case sensitive)
        3. extension.valueCodeableConcept.coding[0].code= “01”
    4. Return an error if a given name is not present
    5. Return an error if a family name is not present
  2. 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.
    1. If patient not found: create a new medical record in the default team of the PKB organisation for the matching ODS code.
    2. Else: Update the demographic details with those provided in the message.
  3. 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.
  4. 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.
  5. Respond. A response, as defined below, is sent to the caller's $process-message endpoint.

Endpoints

Interaction HTTP URL Supported Parameters Permitted User Types Description Examples (more)
operation POST /$process-message
  • async=true. Required. 
  • System
Submit message to PKB for processing. /$process-message?async=true

Request

FHIR PKB Notes
Bundle.id A sender-assigned UUID for the Bundle.
Bundle.type "message"
Bundle.entry[0]: BackboneElement
  • resource: MessageHeader

MessageHeader.id A sender-assigned UUID for the message.  
MessageHeader.event
  • event: Coding
    • system = "http://fhir.patientsknowbest.com/codesystem/message-event"
    • code = "create-or-update-patient"

MessageHeader.destination
  • destination: BackboneElement
    • endpoint. The absolute URL of the PKB $process-message endpoint.

MessageHeader.timestamp When the message was sent.
MessageHeader.source
  • source: BackboneElement
    • endpoint. This must be set to a pre-agreed value configured for the sender's API Client ID. This is the location to which PKB will send the asynchronous response.

Bundle.entry[1]: BackboneElement
  • resource: Patient

Patient.meta
  • meta: Meta
    • tag[0]: Coding
      • system = "https://fhir.nhs.uk/Id/ODS-Code"
      • code. The ODS code of the source organisation for this demographic update.
 
Patient.identifier
  • identifier: Identifier
    • extension
      • url = "https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1"
      • valueCodeableConcept
        • coding
          • system = "https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1"
          • code = "01"
    • value. The NHS number of the patient.
    • system = "https://fhir.nhs.uk/Id/nhs-number"

Patient.name
  •  name: HumanName
    • family = [[User.Family Name]]
    • given[0] = [[User.Given Name]]
    • prefix[0] = [[User.Title]]
Only the first given name and prefix will be processed.

Any other values will be silently ignored.
Patient.telecom
  • telecom: ContactPoint
    • system = "email"
    • value = [[Contact.Value]]


  • telecom: ContactPoint
    • system = "phone"
    • value = [[Patient.Phone]]
PKB only stores a single phone number for a patient. If more than one contact point was provided with a system of “phone”, PKB will use the first one from the list and silently ignore any others.

A ContactPoint with any other system will be ignored.
Patient.gender [[Patient.Gender]]

[[Patient.Gender]] code mappings (FHIR → PKB):
  • unknown → UNKNOWN
  • male → MALE
  • female → FEMALE
  • other → INDETERMINATE

Patient.birthDate [[Patient.Date of Birth]]  
Patient.deceased[x] <conditional>
If the patient is recorded as dead and the death timestamp is known:

  • deceasedDateTime = [[Patient.Death Timestamp]]
Else if the patient is recorded as dead but a death timestamp has not been recorded:
  • deceasedBoolean = true
Else
  • deceasedBoolean = false
 
Patient.address
  • address: Address
    • line[0] = [[Patient.Address Line 1]]
    • line[1] = [[Patient.Address Line 2]]
    • city = [[Patient.City]]
    • state = [[Patient.State]]
    • postalCode = [[Patient.Postal Code]]
    • country = [[Patient.Country]]

Response

FHIR PKB Notes
Resource id A PKB-assigned UUID for the Bundle.  
Bundle.type "message"
Bundle.entry[0]: BackboneElement
  • resource: MessageHeader

MessageHeader.id  A PKB-assigned UUID for the message.  
MessageHeader.event
  • event: Coding
    • system = "http://fhir.patientsknowbest.com/codesystem/message-event"
    • code = "create-or-update-patient"

MessageHeader.destination
  • destination: BackboneElement
    • endpoint. MessageHeader.source.endpoint of the request.

MessageHeader.timestamp When the response was sent by PKB.
MessageHeader.source
  • source: BackboneElement
    • name = "Patients Know Best"
    • endpoint. The absolute URL of the PKB $process-message endpoint.

MessageHeader.response
  • response: BackboneElement
    • identifier. MessageHeader.id of the request.
    • code. ok | transient-error | fatal-error
    • details. Optional reference to a contained OperationOutcome resource.

Subpages (1): Examples
Comments