| Table of Contents | ||||
|---|---|---|---|---|
|
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.
...
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.
...
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.
...
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.
...
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.
Customer | Authentication → | N/A | N/A | N/A | |||
Send data | A Customer can send data to PKB using the HL7 v2 API. | A Customer cannot interact with the Custom REST API. | A Customer cannot interact with the Facade FHIR endpoint. | A Customer cannot interact with the Messaging FHIR endpoint. | A Customer can send any FHIR resource to a Customer FHIR endpoint. | Data cannot be sent to the Aggregated FHIR endpoint. | |
Read demographic data | A Customer can query patient demographics using the HL7 v2 API. See: QRY A19 | Any demographic data a Customer has sent to their FHIR endpoint can be read back from the same endpoint. | A Customer can read data from the Aggregated FHIR endpoint. | ||||
Read clinical data | A Customer cannot read clinical data from the HL7 v2 API. | Any data a Customer has sent to their FHIR endpoint can be read back from the same endpoint. | |||||
Read clinical data from others | A Customer FHIR endpoint only contains data from the owning Customer. | ||||||
Partner | Authentication → | Pending | Pending | ||||
Send data | A Partner can send data to PKB using the HL7 v2 API. | A Partner can send and read data using the endpoints available in our Custom REST API. | Data cannot be written to the Facade endpoint. | A Partner can create or update a Patient resource. See: Process message | Pending | Data cannot be sent to the Aggregated FHIR endpoint. | |
Read demographic data | A Partner can query patient demographics using the HL7 v2 API. See: QRY A19 | A Partner can read data from the Facade FHIR endpoint. | Data cannot be read from the Messaging FHIR endpoint. | Pending | |||
Read clinical data | A Partner cannot read clinical data from the HL7 v2 API. | ||||||
Read clinical data from others | |||||||
App | Authentication → | N/A | N/A | Pending | Pending | ||
Send data | An App cannot interact with the HL7 API. | An App can send and read data using the endpoints available in our Custom REST API. | Data cannot be written to the Facade endpoint. | An App cannot interact with the Messaging FHIR endpoint. | Pending | Data cannot be sent to the Aggregated FHIR endpoint. | |
Read demographic data | An App can read data from the Facade FHIR endpoint. | An App can read data from the Aggregated FHIR endpoint. | |||||
Read clinical data | |||||||
Read clinical data from others | |||||||
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 Messaging CapabilityStatement 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).
...
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.
...