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).
...
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:
...
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 or unregistered. Note that you can also send questionnaire requests to patients that were discharged or that have sharing disabled using this method. You can target up to 500 patients individually.
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, whether they are registered or not. 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 by following this example. 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.
...