Welcome

If you have questions about using the API, or would like to set up a call to discuss integration, email us on integrations@patientsknowbest.com.

If you find a bug, or think our service isn't working as expected, you can raise a helpdesk ticket by emailing help@patientsknowbest.com.

We are always updating our developer APIs with more features; subscribe to our developer blog so we can keep you posted!

Tutorial

PKB supports a variety of different workflows and use cases for interacting with our APIs.

The information below is provided for reference, but our Integrations Team will work through all of this with you.

Step 1: Integration Type

Using the information below, determine which Integration Type is most appropriate for your integration.

Customer

A Customer interacts with PKB APIs directly, using credentials issued to the organisation.

A Customer is normally an organisation providing healthcare directly to patients. A Customer will be working / have worked with PKB’s Success team as part of managed deployment, and will have access to the web interface for e.g. Team Coordinator and Professional accounts.

A Customer is responsible for managing messaging issues. For example, the Organisation Administrator is responsible for manually reviewing queued HL7 messages.

Example: An NHS trust wants to send appointment data to PKB so that patients know when their appointments are scheduled.

Partner

A Partner integration interacts with PKB APIs on behalf of a Customer. The Partner must first be granted an identifier by PKB. This is a prerequisite to interacting with the APIs.

Subsequently, the Partner can interact with PKB APIs if and only if a Customer (organisation or team) chooses to grant access. The Partner will have a level of access bounded by the Customer’s level of access.

For example, if a team grants access to a Partner, the Partner will not be able to view Patient data which was not available to the granting team.

Note: A Partner would typically be a third party company, but there is no technical requirement for this to be the case. A Customer might set up an in-house integration that makes use of the Partner architecture, in order to perform a task on their own data.

Example: A third party appointment partner wants to offer change/cancel functionality to an NHS trust so that patients are able to manage their appointments in PKB. This Partner should only be able to modify the appointments of Customers that have granted them permission to do so.

To start as a partner, please read the documentation on Partner integrations with Patients Know Best.

App

An App integration interacts with PKB APIs on behalf of a registered PKB user. The App must first be granted an identifier by PKB. This is a prerequisite to interacting with the APIs.

Subsequently, the App can interact with PKB APIs if and only if a user chooses to grant access.

This is the appropriate architecture for SSO implementations.

Example: A mobile app wants to allow a patient to link their blood pressure device to their PKB account so that blood pressure readings are automatically sent to PKB.

Step 2: API selection

Using the table below, determine which APIs are most appropriate for your integration.

Step 3: Check capabilities

After selecting a high level Integration Type and API(s) for your use case, it is important to check that the current capabilities supported by PKB meet your needs.

HL7 v2

See the Messages section of our HL7 API documentation for the full list of HL7 v2 messages supported by PKB.

Custom REST API

See our Swagger documentation for details of supported interactions in the Custom REST API.

Facade FHIR endpoint

See the Facade CapabilityStatement for the full list of capabilities of the Facade FHIR endpoint.

Messaging FHIR endpoint

See the for the full list of capabilities of the Messaging FHIR endpoint.

Customer FHIR endpoint

Each Customer FHIR endpoint already supports the standard REST interactions for each FHIR Resource in the corresponding specification (STU3 or R4).

It is not possible to tailor this functionality with custom operations, or to add support for the messaging paradigm.

However, note that the data you send to a Customer endpoint is not available to anyone else (including the patient) until PKB has added aggregation support for the relevant Resource type. It is therefore important that you also check the capabilities of the Aggregated FHIR endpoint to ensure your use case can be met.

Aggregated FHIR endpoint

See the Aggregated CapabilityStatement for the full list of capabilities of the Aggregated FHIR endpoint.

Step 4: Obtain access to the APIs you need

All our APIs require some form of client authentication. The authentication will vary slightly by API, but in all cases you will need PKB to issue you with the relevant client credentials, even for our testing environments.

If you haven’t already done so, please get in touch with integrations@patientsknowbest.com who will be happy to help.

Step 5: Hello, world!

Once you have client credentials in place, it is normally helpful to get a simple API call working. This will ensure the wiring is correct, and will give you a starting point to work from.

Once you’re up and running, your development can continue in line with your integration objectives.

This page has provided a brief overview of how to get started; for more details, and information about progression to production, you might like to explore the Integrations section of the PKB Deployment wiki.

In any case, your development activities will be supported by the PKB Integration Team, who you can always reach on integrations@patientsknowbest.com.