IT Department Documentation about Patients Know Best

This document is for the IT team at a health care institution integrating its electronic health records system (EHR) with Patients Know Best (PKB). Full specifications of the HL7 API and the REST API are available at The rest of this document provides a summary of the HL7 integration information. The PKB team look forward to working with you.

What does the PKB platform include?

PKB have three  main features: a back-end EMR, a front-end view of the data specific to patients and clinicians, and workflow tools for both:

  1. A back-end electronic medical record, able to store all the records that are in a standard EMR package like EMIS or iSoft, but also encrypting each patient’s data using a patient-specific key.
  2. Front-end views of the data that are role-specific, e.g. the patient can look at their own medical record and that of consenting family members; the clinician can see the records of all the patients they are treating; the coordinator can manage the access rights to the records and manage treatment plan templates, without seeing the actual records.
  3. Workflow tools for patients and clinicians to work together, including messaging and online consultation.


What are the steps involved in integration?

See the HL7 API integration steps or the REST API integration steps

How are data transferred into PKB?

PKB supports HL7 message data transfer over an authenticated, HTTPS connection using web services (SOAP). It is easiest to begin with laboratory results (see documentation for pathology departments), both because the data formats are simple, and because clinicians are least anxious about giving patients access to these. Over time, other systems can be integrated, including radiology, medications, letters, and ultimately the medical notes written in clinic. We aim for total integration, sharing all medical records with each patient, to provide the best and most efficient medical care.

The integrating institute tracks the patients who have been activated in PKB. The initial list of active patients can be fetched with an unfiltered QRY_A19 query, then the institute polls with regular A19 queries (filtered by timestamp) to fetch new patients that have been activated (or with ID modifications) since the last check.

Implementation notes:
  • Patient identity validation: PKB enforces checksums where available (for example, in NHS numbers) but does not enforce matching name, DoB, etc. from incoming PID segments with the patient’s info. Instead, basic demographic info is included in A19 query responses, so each institution can decide what rules to enforce before adding a PKB patient to the “active” list.
  • a patient may be returned for different timestamp-filtered queries over time, triggered by the addition or modification of either national ID or institution-level ID, so adding patients to the active list should not fail if the patient is already in the list.
  • There is currently no separate query to return patients that should be removed from the active list. This is because in the vast majority of cases, an inactive patient will also have no results to deliver; if results are submitted to PKB for an obsolete ID, or for a patient who is not actively linked to the connecting institution, the PKB API will return a validation error (so the message should be logged for review). The institute may clear any obsolete records if needed by periodically clearing the active patient list and repopulating it with an unfiltered/full-list query.

All connections are one-way (institute to PKB); PKB does not open connections to the institute. There is more information below on why PKB doesn’t report new patients to the institute directly.

What network traffic must be permitted?

During integration setup and testing, any servers/PCs at the institute that will send HL7 messages to the PKB test server will need to be allowed to make TLS connections to (IP on port 7443 or (IP on port 7444. PKB does not need the list of IPs which will connect to the test server.

For production connections (sending actual patient data), the connection options depend on your environment:

For any production connections, PKB will need to know the list of IP addresses that will connect to the production server, for firewall and connection security.

It is best to start integration by connecting to the UAT server with sandbox accounts for quick feedback and testing. However, some UK NHS institutions are not able to open up their firewall to outgoing non-N3 connections, and in those cases we can use a sandbox account on the production server. (Debugging is slower on the production environment, but this can sometimes be faster than waiting for permission to connect to the non-N3 UAT server.)


To use the REST and FHIR APIs no whitelisting is required by PKB as the authentication is secured with OAUTH2.  Your network must allow HTTPS (port 443) traffic to the target environment to use the APIs. Environment IPs as described in the section above.

What is the format of the HL7 messages?

Information on our supported HL7 messages can be found here.

Patient demographics mismatches

The institute should validate the patient demographic data returned from the A19 query with its own patient, to flag the record internally for human followup.

Team coordinators on PKB can edit NHS number & demographic info for any patient on their team, as can patient clinicians.

Can PKB notify the organisation directly of patient activity?

PKB will switch on publish and subscribe functionality in the near future. This will provide outgoing notifications to organisations when new patients are added. It will also notify of any new data in the patient's record e.g. a new symptom they entered, a measurement from a device, a message to a professional or a test result from another organisation. If you would like to take part in our beta testing please contact


Where are data stored?

Data are stored on PKB’s EMR, which is inside the NHS N3 virtual private network, and hosted under ISO 27001 protocols for security. Each patient’s data are encrypted using a different key, specific to that patient.
How are data destroyed?

We only destroy the medical record if the patient requests us to do so, and the clinical team staff confirm to us that the patient is able to provide informed consent for this. Otherwise, we keep the data safely stored for use by the patient and their medical team.

How are the data encrypted?

Firstly, for all communication between clients and the PKB servers, and even between the PKB servers in the datacenter, we use TLS with high grade (AES-256) encryption. We do not support unencrypted HTTP for browser requests, and internal communication between the web application, EJBs, LDAP, and database are all over TLS as well.

Secondly, medical data arriving from users or through APIs are immediately encrypted using DESede (Triple DES). The secret key is stored with each document after being encrypted using the 1024-bit RSA public key that is unique to that patient account; thus, the secret key (and the document) cannot be read except by users who have explicitly been granted access by the patient. Each user has their own asymmetric key pair, encrypted using their password (DESede triple DES encryption), so the process of granting access encrypts the account private key using the new user's public key.

Thanks to this system, even a theoretical intruder (including a trusted PKB employee) with the root password and access to the application source code and database still would be unable to access private medical data. Furthermore, even if a single patient's account were compromised, that would not affect the security of other patient data in the system.

Where are passwords stored?

Each user's password remains with the user. PKB stores is only a randomized "one-way" hash of the password. The hash verifies that the password the user entered is valid but cannot recover the password itself (it remains with the user). PKB never stores the password in our system in clear text or in any form that can be revealed to anyone with access to the PKB System.

Is PKB vulnerable to SQL injection attacks?

No, PKB does not pass any user-provided strings directly to the database layer.


What ability does the clinician have to stop a patient reading an entry or getting a result?

PKB receives data as they are released from the hospital IT system. Once the data are copied into the patient’s account, the patient has full access to and control over these data as PKB is their personal medical record.

Medical institutions are able to differentially sequence the release of data, e.g. full blood count results are released immediately while HIV positive status is only released after counseling a patient. However, industry best practice is for institutions to start by using PKB in one department with patients who already know their diagnosis and have demonstrated informed consent to what it means to access their data. In parallel, the PKB team can provide advice to the institution on the optimal release of data across all departments. The final decision for the local protocol of each institution rests with their clinical governance committee, and is guided by the experience of the first department with its first cohort of patients.

What support are clinicians provided with to explain to patients what terminology/results mean?

The labs/results data in PKB are automatically annotated with explanations from the Royal College of Pathology with additional explanations for what the results might mean given they are high, low or within normal range. Clinicians do not have to translate medical terminology, but they should – as part of GMC good medical practice – avoid abbreviations because these are ambiguous to clinicians and patients.


Who deals with patient access problems? When is support available?

If a patient forgets their password, there is a password reset process requiring the patient’s demographic details and security question. If the patient still cannot remember their password, they can request a reset by clinical staff. PKB employees cannot help with access as all the data are encrypted and we do not have decryption rights.

However, patients often contact us directly (by clicking the “Help” link on every page) to ask about using the software. Our staff answer these questions within 1 working day.

What browser type and version does PKB support?

We test PKB so that it works within Internet Explorer 11 upwards for NHS computers. The web site also works with any modern standards-compliant browser, including versions of Chrome, Firefox and Safari. PKB's policy is to support new browsers as they arrive in the market and to support new devices with our responsive HTML.

PKB is also tested with screen readers by users with visual disabilities like Thalidomide Trust beneficiaries, and is compliant with RNIB guidelines for colour-blind users.

Finally, we are optimising the website for small screens, e.g. iPhone and Android smartphones.