The roadmap represents PKBs FHIR API development strategy, and therefore all information and API specifications contained here are subject to change.

General overview

PKB will provide a fully-functional bidirectional FHIR API, for the persistence and retrieval of data, to and from the PKB application. This API will support all FHIR resources which are defined in R4, the landing page for which is available here, with a navigable list of available resources.

The inbound FHIR API will provide sending systems with the capability to add, update or delete data points within the PKB application, using FHIR messaging in JSON format. The FHIR API endpoints provided will be RESTful, maning each message must contain one, and only one resource, although a message may reference other resources which have previously been sent.

The expanded outbound FHIR API will provide receiving systems with the capability to retrieve data points that they are authorized to view, returning the results in the appropriate R4 resource in JSON format.

Supported resources within the PKB application

All FHIR resource endpoints will be supported for data persistence by PKB from the point the inbound FHIR API goes live. However, data which is persisted via the inbound FHIR API will not display through the PKB UI or integrations until that resource is adopted for inclusion within the core PKB application. The order in which resources are included within the core PKB application is responsive to customer requirements.

At the point the inbound FHIR API goes live, PKB intend to support the display and integration of the following resources into the core PKB application:

  1. Patient

  2. Condition

  3. Medication

  4. MedicationStatement

  5. Appointment

  6. Slot

  7. AllergyIntolerance

  8. Organization (references to this resource by other resources)

Not all fields on these resources will be supported initially: individual resource definitions for the current supported specification of these resources will be provided shortly. Any unsupported fields will be silently ignored by the core PKB application for UI and integrations, although they will still be persisted successfully. The inclusion of additional values or features is, again, responsive to customer requirements.

To emphasise, sending systems will be able to persist data to PKB via all R4 FHIR API endpoints from the point the inbound API goes live, even if those resources are not yet integrated into the core PKB application.


The most typical use cases for the inbound FHIR API involve the creation or updating of patients, the triggering of invitations, and the addition of clincial data points to patient records.

For clinical data points to be added to a patient via the FHIR API, that patient must first be provided to the API in a Patient resource, even if the patient already exists on PKB. This provides the mapping between the real-world patient, as denoted by an NHS number, and the patient on the sending system, denoted by a sender-specific UUID.

Sending systems will typically achieve this through an initial “bulk load” of their patients and clinical data points onto the PKB system once they go live with the API, and thereafter with real-time or periodic messaging to propagate changes.

All messages must be “state of the world”, i.e. the state of the resource at the point the message is being sent. Upon receipt PKB identifies if a resource already exists by matching on the resource’s UUID. If it does not exist, it is created; if it does exist, the fields which differ will be updated. A resource UUID is therefore mandatory for all messages.

Authorization to e.g. update an existing resource is centered around the source organisation of that data point. The source organisation of the data, defined as a reference to the appropriate Organization resource, is therefore also mandatory for all messages.

When updating fields, the following business logic is applied:

• All textual values will have leading and trailing whitespace removed before being stored

Empty values are not permitted in FHIR. Any attribute not provided, or else not supported by a resource, will not be modified. If the caller wishes to explicitly delete a value stored for a given field, they must provide the data absent reason extension. PKB will not store or process the specific reason provided, but will use the presence of the extension as an indicator that the value should be deleted. This is comparable to the HL7 Null Value in the HL7 v2 API specifications. The caller should particularly be aware of this behaviour when updating compound values, such as the patient’s name and address.

All patients created via the inbound FHIR API are automatically assigned to the default team for the sending organisation. This default team is designated by the sending organisation, and must be recorded on PKB before any data is sent.

Inbound transactionality

All messages sent to PKB are processed synchronously per endpoint, per connection. There is therefore no guaranteed processing order when messages are sent to different endpoints, or to the same endpoint through multiple connections. Only the return of a synchronous acknowledgement guarantees that the message has completed processing, and subsequent messages reliant on that resource should be sent.

Acknowledgments and error handling

Integrating systems will receive a positive or negative acknowledgement once processing of the message has completed. This acknowledgement will consist of a HTTP status code and, for errors, an OperationOutcome resource where possible. For outbound messages, a successful response will contain any relevant, authorised resources that have been requested.

Although PKB will store audit information as to message success or failure, it is fundamentally the responsibility of integrating systems to monitor their message streams and audit and/or alert appropriately for failed messages.

Subsequent interaction with resources

It is the integrating system’s responsibility to maintain access to the UUIDs used to uniquely identify a resource when it was sent to PKB. This UUID, and solely this UUID, allows for an unambiguous resource match which permits subsequent modification, reference, or read by id.

Resource mapping summary

This section provides early visibility of resources which are under development.

Please see the subpages for full details of each resource.

Details of our resources already supported on production can be found in the Resources section of this site.

Operation summary

This section provides early visibility of operations which are under development.

Please see the subpages for full details of each operation.

Details of operations already supported on production can be found in the Operations section of this site.