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:

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

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