Code sets

Overview

There are several fields in our HL7 API which accept coded data. These come in 3 different flavours.

Code set flavours

Standardised codes

Some of the fields have a mandated code set. Where this is the case, we provide the relevant code set that you must use.

Local codes (mapped by PKB)

Other fields do not have a mandated code set, but we ask that you let us know what codes you will be using. By providing your code set, we will be able to process your data in a way that allows us to add extra value, for example by mapping laboratory test codes to show test names in the user's language along with explanations and links to extra information. Please see the notes column below to understand more about how we use your data.

Local codes (for local use only)

Finally, some fields do not have a mandated code set and are not mapped to standardised codes. These fields are typically not processed by PKB beyond a simple store, retrieve and display, so you are welcome to send through your own local codes and do not need to tell us what they are.

Summary of coded fields

Segment	Field	Description	Flavour	Notes
PID	8.1	Gender	Standardised – PKBCS01
PID	13.2	Use Code	Standardised – PKBCS02
PID	14.2	Use Code	Standardised – PKBCS03
OBR	4	Order/Service ID	Mapped	Declaring this code set helps PKB to automatically apply meaningful privacy labels.
OBR	24	Discipline	Mapped	Declaring this code set helps PKB to show a user friendly name in the web interface.
OBX	3	Test ID	Mapped	Declaring this code set allows PKB to map your codes to standard LOINC codes. This allows meaningful comparison between results sent from different institutions, and allows us to explain the result to the patient in their own language.
OBX	6	Unit ID	Mapped	In order to map OBX-3 Test IDs, it is important that we also know what units your tests are measured in.
SCH	8	Appointment Type	Local
PV1	2.1	Patient Class	Standardised – PKBCS04
PV1	10.1	Hospital Service	Mapped	Declaring this code set helps PKB to automatically apply meaningful privacy labels. It also allows us to show a user friendly name of the hospital service (aka specialty) in the web interface.
TXA	2.1	Document Type	Standardised - PKBCS05

Supplying mapped code sets

Any of your mapped code sets can be added, changed or removed at any time.

An Organisation Administrator is also able to view and download them, please see the user manual for details of how to do this.

To request a change, please email help@patientsknowbest.com, including the following information:

Your HL7 username. This allows us to identify your interface.
Which server environment you would like to update (e.g. sandbox, UK production)
Which code set you would like to be updated (e.g. Hospital service)
An attachment containing the full code set, in the correct format (see example file). Please do provide the full code set each time you request a change, as this has proven to be the safest way of avoiding miscommunication. After the update has been applied, we will confirm which codes were added/removed/changed. We encourage you to confirm the change has been successful by checking the end result using your Organisation Administration login.

The updated code sets will only affect data processed after they have been applied.

Order/Service ID

PKB uses your Order Service Code Set for 1 function:

Helping to determine the privacy label for a data point

To supply this code set, please provide a CSV file in the following format: Code, Display, Privacy Label

Code. The value that will appear in OBR-4.1
Display. The name of the order/service. The value provided will not be used directly but is helpful to have when discussing your code set.
Privacy Label. One of: GENERAL_HEALTH, MENTAL_HEALTH, SEXUAL_HEALTH, SOCIAL_CARE.

See here for an example file.

Laboratory Discipline

PKB uses your Laboratory Discipline Code Set for 1 function:

Replacing the code with a user friendly display name in the web interface

To supply this code set, please provide a CSV file in the following format: Code, Display

Code. The value that will appear in OBR-24.1
Display. The name of the laboratory discipline that we should show to the user in the web interface.

See here for an example file.

Hospital Service (Specialty)

PKB uses your Hospital Service Code Set for 2 functions:

Helping to determine the privacy label for a data point
Replacing the code with a user friendly display name in the web interface

To supply this code set, please provide a CSV file in the following format: Code, Display, Privacy Label

Code. The value that will appear in PV1-10
Display. The name of the hospital service that we should show to the user in the web interface.
Privacy Label. One of: GENERAL_HEALTH, MENTAL_HEALTH, SEXUAL_HEALTH, SOCIAL_CARE.

See here for an example file.

PKB code sets

PKBCS01

Value	Description
U	Unknown
M	Male
F	Female
I	Indeterminate

PKBCS02

Value	Description
NET	Email address
PRN	Phone number
PRS	Mobile phone number

PKBCS03

Value	Description
NET	Email address
WPN	Work phone number

PKBCS04

Based on FHIR EncounterClass (DSTU2).

Value	Description
I	Inpatient: An encounter during which the patient is hospitalized and stays overnight.
O	Outpatient: An encounter during which the patient is not hospitalized overnight.
A	Ambulatory: An encounter where the patient visits the practitioner in his/her office, e.g. a G.P. visit.
E	Emergency: An encounter where the patient needs urgent care.
H	Home: An encounter where the practitioner visits the patient at his/her home.
F	Field: An encounter taking place outside the regular environment for giving care.
D	Daytime: An encounter where the patient needs more prolonged treatment or investigations than outpatients, but who do not need to stay in the hospital overnight.
V	Virtual: An encounter that takes place where the patient and practitioner do not physically meet but use electronic means for contact.

PKBCS05

Value	Description
AF	Audio File
AL	Appointment letter
AN	Alert notification
BR	Birth report
CL	Clinic letter
CP	Care plan
DL	Discharge letter
DS	Discharge summary
MDT	Multidisciplinary team meeting notes
RL	Referral letter
TCI	Admission (TCI) letter
HS	Health screening report
TT	Timetable
SP	Signposting document
ST	Support document
QR	Questionnaire response
CR	Clinician review summary
OR	Operative report
RAL	Referral acknowledgement letter