Overview
This page outlines the process of sending questionnaire requests and retrieving the corresponding questionnaire responses to patients using PKB FHIR API.
Workflow
Sending questionnaire requests
The $send-questionnaire-request FHIR operation allows you to send a questionnaire request either to a few specific patients or to a whole team in one call.
Step 1: Find the URL to send your requests to
Prerequisite: much like the other façade FHIR APIs, you need to be able to generate an access token (you can do so by following the OAuth 2.0 walkthrough).
To send questionnaire requests, you need to choose which questionnaire you will send and find its corresponding id. This can be done by sending a request to our Questionnaire Search API, following this example. You will get all your questionnaires back and can find the appropriate questionnaire id.
Once you know the id, you will be able to infer to which URL you should send your request, e.g:
https://sandbox.patientsknowbest.com/fhir/Questionnaire/<questionnaire-id>/$send-questionnaire-request
This example is written for http://sandbox.patientsknowbest.com, but you can replace the URL as needed if you are connecting to a different environment.
Step 2: Ask for your clinician id
On questionnaire request creation, PKB will notify the patient that they have been asked to fill in a questionnaire both by email and a message in PKB. For this reason, you need to choose a PKB professional account from which these messages should appear to be from in the patient’s record. As of now, you need to get in touch with us to know the ID of one of your clinician's professional accounts so that you can use them as a requestor in your API call.
Please note that this id changes according to the professional team membership, so you should provide both their email and team so that we can provide you the right id.
Step 3: Make an API call
As per the specification, only two parameters are mandatory in the body of the request to make a call:
a requestor parameter: it has to be represented as a Reference URL, e.g: ‘Practitioner/<clinician-id>’ (the id being the one that you asked for in step 2)
one or several target parameters, which represent to which resource you wish to send questionnaire requests to. These parameters can point to:
Patient(s)
using their national id, by sending a Reference including the national id as an Identifier. This identifier is a pair of (system, value) that represent the national id as per FHIR specifications.
using their PKB id, which you can find by using their national id and the Patient API, following this example
a Team
using the team id, that needs to be provided by PKB for now, following this example
You can send either to several target parameters that point to Patients, or to a single parameter that points to a whole team. The requests will be sent to any patient in the team, even if they are unregistered.
Sending to a few specific patients
If using the API for only a few specific patients, you can send questionnaire requests to any patient that is in your org network, even if they are not part of your organisation. Note that you can also send questionnaire requests to patients that were discharged or that have sharing disabled using this method.
Sending to a whole team
When sending questionnaire requests to a whole team, only people that were not discharged and with sharing enabled will receive the request. Deceased patients are also excluded from this operation.
Step 4: Add optional parameters
Some optional parameters are available for this operation:
notificationFlag: this code parameter allows you to enable or disable email notifications sent to the requestor when a patient fills in a questionnaire response for this request. Accepted values are: ‘EMAIL_NOTIFICATION_ENABLED’ or ‘EMAIL_NOTIFICATION_DISABLED’. If no notificationFlag is provided, it defaults to enabled.
additionalIdentifier: if you are sending a request to just one specific patient, you are allowed to add an additional identifier (for example; a surgical order ID from the hospital clinical system), so that matching the responses to the data from your other software is easy and can be automated.
Step 5: Read the response bundle
From the API call, you will get a response Bundle that encapsulates all the questionnaire requests that were created in the form of a URL (ProcedureRequest/<id>). If something went wrong for any of the requests, you will get an error back explaining why the request could not have been created.
If you want to see in further detail the Procedure Request that was created, you can do so by using the Procedure Request API, following this example.
Retrieve Questionnaire Responses
Responses are available through the Questionnaire Response Search API. Multiple optional parameters allow you to find the questionnaire responses that match your criteria. An example of this endpoint usage can be found here.
Retrieving Questionnaire Responses that match a specific additional identifier
If you added an additional identifier when sending the questionnaire request initially, you will be able to retrieve the questionnaire responses that specifically match this procedure request. These responses were created when patients clicked the link in the email they received for the questionnaire request and submitted a response, so generally, only one questionnaire response will match this identifier. However, if the patient clicks a second time on this link, they will be able to submit a second response matching the same Procedure Request identifier. The following diagram shows this workflow.
