Developer documentation‎ > ‎HL7 API‎ > ‎


PKB supports the tracking of Encounter information. An Encounter is a grouping of related messages, e.g. an admission and discharge for a single visit can be grouped into an Encounter. This page provides an overview of key points relating to the handling of Encounters; see here for the relevant message specifications.

Encounters are externally specified. PKB requires sending systems to populate PV1-19 to indicate that a message relates to the specified Encounter.

The following PV1 fields fields are supported:
  • PV1-2: Patient class.
  • PV1-3: Patient location.
  • PV1-7: Attending doctor.
  • PV1-8: Referring doctor.
  • PV1-9: Consulting doctor.
  • PV1-19: Visit ID. This is used by PKB to uniquely identify an Encounter for each sender.
  • PV1-44: Admit datetime. Timestamp of admission for entire Encounter.
  • PV1-45: Discharge datetime. Timestamp of discharge for entire Encounter.
We use A01 (admission), A02 (transfer) and A03 (discharge) to track Encounters. However, we're flexible about their usage. When each message is received we will look for an existing Encounter with the specified PV1-19 value. If an Encounter is not found, one will be created, regardless of the message type. Subsequent messages with the same PV1-19 value will be added to this Encounter.

An A08 (update) can be used to update information about a specific Encounter. Note:
  • Demographic information in PKB is not associated with a specific Encounter. You should therefore use A28 or A31 to update this information.
  • An A08 will be treated as reflecting the full set of relevant information; you should send this message fully populated, not just with the values that you'd like to change.
An A01, A02, and A03 can be respectively cancelled using A11, A12 and A13. Upon receipt of a cancellation message, PKB will identify the most recently received message of the type to be cancelled, which belongs to the specified Encounter. This message will then be deleted. It will not be shown to the patient by default, but they will be given an option to see deleted information.

Some data types sent via HL7 (e.g. documents) which are not directly related to tracking patient location can be associated with a specified Encounter by setting PV1-19 appropriately. This will allow PKB to link the data points to the Encounter to show to the patient more meaningfully.

Note - PKB can not yet track related groups of Encounters. For example, a series of 5 related follow up appointments are treated as 5 separate Encounters, providing that the sender has specified a unique PV1-19 value for messages relating to each of the appointments. There is no superordinate ID that can be used to link these together at this stage.

Messages sent and received as part of a conversation within PKB are treated as Encounters with an EncounterClass of VIRTUAL.