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.
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.
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.
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.
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.
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 firstname.lastname@example.org 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.