Developer tutorial

The documentation below is for developers to start integrating with PKB. For information on why to start integrating with PKB and what resources to set aside please read our general documentation integration tutorial.

PKB Basics

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.

Technology stack diagram.cropped.png


Information is kept confidential so that only the patient, and the people the patient chooses, are able to access the patient’s medical records. PKB encrypts data so that it is unable to access the data, let alone leak it, therefore only patients or clinicians can leak patient data. PKB is responsible for the encryption in its software. Patients and clinicians are responsible for not leaking the data they have access to.

Non-clinical information stored unencrypted include the patient’s:

  • Name

  • Date of birth

  • Address

  • Identifiers (national, organisation and team)

These are unencrypted so as to identify the record into which new clinical data must be stored with the correct patient’s public key.

These data points are stored with ISO 27001 security i.e. so that no PKB staff have access rights to the data.

PKB’s encryption has three layers:

1. Medical record data storage layer: encrypts medical data using DESede (Triple DES), a unique public and private key for each patient. Only the patient, and the people the patient chooses, have a copy of the private key. 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. Only the private key allows accessing the patient’s data. Therefore, no other parties are able to access the patient’s data.

2. Secure server holding the data: this is hosted to ISO 27001 standard inside the NHS N3 network, behind the NHS firewall. This protects against malicious hacking attempts and provides uptime, disaster recovery and business continuity guarantees.

3. Transport through TLS: 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.

Who can access the system?

Every authorised user is either a patient who has been identified and consented by a medical professional; or a professional whose employer (e.g. NHS hospital or County Council social worker) has identified and authorised them to use the system. The patient may choose to invite a carer or professional who has not been formally identified, but these unverified accounts cannot be used with any other patients. There is a full audit trail of who gave who access to which accounts.

More info:


Ownership and responsibilities

Servers: PKB is in charge of the servers and they reside within a secure network under ISO 27001 hosting. Data are encrypted so that only the patient, and the professionals that the patient chooses, can access the patient’s data. PKB ensures this continued compliance.

Software: Intellectual property for the software and its features are owned by PKB. PKB is responsible for maintaining its software and servers. PKB’s software is mature and has already been extensively tested by many organisations across many care settings, so no additional changes are required for PKB customers to provide a smooth service to their patients. PKB regularly updates the software based on feedback and requests from users, and an update from one user’s request is made available to all customers with each PKB server upgrade.

Content: Intellectual property for any care plans created is owned by the clinical team which created the care plans.

Data: The copy of data in a patient’s account is owned by the patient. The copy of data in a clinician’s account is owned by the employer of the clinician. No party can edit or delete data as this is a medico-legal record. Patient, carers and clinicians can add new data and comments to improve the accuracy of the record, and all additions are tracked with an audit trail.

Training: Customer training is provided by registered nurses employed by PKB. They are clinicians who have received specialist training in delivering workshops to people using the system. The training is delivered by either workshop format or online webinar. Technical support is provided to employees of PKB customers as part of the service contract.

Monitoring: Each customer monitors the use of the system in accordance with their existing policies. The customer also monitors compliance with the system, in accordance with their existing policies. PKB does not have access to individual accounts of clinicians or patients.

More info:

Notifications: Each patient can add data to their own account – the account is not the property of the customer, and thus not the responsibility of the customer. There is a clause contained on every appropriate page in PKB that removes liability from clinicians if they do not see or access information uploaded. When a patient explicitly wants to communicate with a customer clinician about an upload, the clinician will receive a notification by email to their chosen customer email address.

Account Activation

When the first email address for a patient is added to their medical record, the patient will automatically be sent an invitation to register. The invitation email will contain a link that the patient must click, after which they will be presented with a Date Of Birth (DOB) challenge, followed by the main registration screen.

If the DOB is known to PKB at the time of registration, the patient must enter the correct value to progress past this screen. This acts as a security check. If the DOB is not known to PKB at the time of registration, then the patient’s answer is automatically treated as correct, and added to the PKB medical record.

More info:


HL7 Track

The PKB HL7 interface accepts HL7 2.x messages over SOAP, converts them to XML and passes them into the main PKB back end for processing.

HL7 Integration Steps


More info:


Fill out the form to receive access to HL7 connectivity

Message Specs

Standard Segments

QRY^A19: Query for patient demographics

ADT^A28 and A31: Create and update patient medical records

ORU^R01: Send observations

MDM^T02: Send medical documents

SIU^S12, S13, S14, S15, S26: Manage scheduled appointments

ADT’s Managing Encounters

Patient Matching

PKB supports 2 types of identifier in the HL7 API: national and local. A national identifier is an identifier that identifies a patient within a given country, such as an NHS number. A local identifier is an identifier which identifies a patient uniquely for a sender, but not outside that sender. An example would be a hospital number. A local identifier can be associated with either a PKB Organisation or a PKB Team.

More info:

Code Sets

There are several fields in our HL7 API which accept coded data. These come in 3 different flavours: Standardised, Local mapped to PKB and Local.

More info:

REST Track

The REST API allows developers to quickly and easily interact with PKB functionality in a programmatic way, including accessing patient medical records.

REST API integration steps

Information Sharing Agreement


Test against our Open API specifications

Scope Authentication

There are 3 different types of user in PKB which can authenticate against the REST API:

  • Patient

  • Clinician

  • Team Coordinator

Each REST operation is restricted to one or more of these user types. The scope of each operation defines which user types are authorised to call it, and is specified in the documentation for each operation.

More info:

Obtain a REST API ID

In order to interact with the PKB REST API, you must identify yourself to PKB. The Client ID allows us to know who you are.

REST API Authentication

Authentication and authorisation in PKB are through OAuth 2.0 after determining the scope based upon the operations you would like to test against, request an API ID (System for Coordinator/Clinician, client for Patient) and follow the steps outline here:

Pub/Sub API

PKB does not offer a formal publish and subscribe mechanism. Clients cannot dynamically register their interest in certain data, and the data itself is never pushed out to a client.

However, PKB will offer push notifications to inform EHR systems that new data is available in PKB for a given patient in PKB. These messages will not contain the data itself. This architecture requires a static endpoint. PKB will then push a notification to this endpoint whenever new data is available in PKB for a patient's record.

More info: