...
Sending questionnaire requests
The $send-questionnaire-request FHIR operation allows you to send questionnaire requests 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 generate an access token (you can do so by following the OAuth 2.0 walkthrough).
In order to send questionnaire requests, you need to chose which questionnaire you will send and find the its corresponding id. This can be done through the Questionnaire API.Once the id is known you can 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:
| Code Block |
|---|
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
PKB notifies On questionnaire request creation, PKB will notify the patient that they have been asked to fill in a questionnaire both by an email and a message. For this reason, you need to chose a professional that will send the requests messagesappear to have send these requests messages (although that is done automatically as part of the API). As of now, you need to get in touch with us to know the id of one of your clinicians so that you can use them as ‘requestor’ in the FHIR operation requestor in your API call.
Step 3: Make an API call
According to the specification, you only need 2 parameters to make an API two parameters are mandatory in the body of the request to make a call:
a ‘requestor’ ID ( 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 you need to get in touch with to find
You can send either to several target parameters that point to Patients, or to a single parameter that points to a whole team.
Sending to a few specific patients
You can send to specific patients either by:
...
Using their national id
...
If using the API for only a few specific patients, you can send questionnaire requests to patients that were discharged or that have sharing disabled. You can send questionnaire requests to any patient that is in your org network, even if they are not part of your orgorganisation. 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 were added to the are available for this operation:
notificationFlag: This this code parameter allows you to enable or disable email notification 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 only to one specific patient, you are allowed to add an additional identifier (for instance a business identifier coming from another software), so that the matching between the responses and with the data in from your other software are becomes easy to be matched together.
Step 5: Read the response bundle
...
If you want to see in further details the Procedure Request that was created, you can do so by using the Procedure Request API, following this example.
Retrieve Questionnaire Responses
...
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 patient clicked the link in the email they received for the questionnaire request and submitted an answera 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.
...