Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Overview

This page outlines the process of sending questionnaires requests to patients using PKB FHIR API, and how to retrieve the corresponding Questionnaire Responses.

Workflow

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 requests to

Prerequisite: much like the other façade FHIR APIs, you need to be able generate an access token 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 corresponding id. This can be done through the Questionnaire API.

Once the id is known you can infer to which URL you should send your request:

https://sandbox.patientsknowbest.com/fhir/Questionnaire/<questionnaire-id>/$send-questionnaire-request

This example is written for http://sandbox.patientsknowbest.com, replace the URL as needed if you are connecting to a different environment.

Step 2: Ask for your clinician id

PKB notifies 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 messages. 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.

Step 3: Make an API call

According to the specification, you only need 2 parameters to make an API call:

  1. a ‘requestor’ ID (that you asked for in step 2)

  2. one or several target parameters, which represent to which resource you wish to send questionnaire requests to.

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:

  1. Using their national id

  2. Using their PKB id, which you can find by using their national id and the Patient API

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 org.

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.

Step 4: Add optional parameters

Some optional parameters were added to the operation:

  • notificationFlag: This code allows 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 the data in your other software are easy to be matched together.

Step 5: Read the response bundle

From the API call, you will get a response Bundle that encapsulate 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 details the Procedure Request that was created, you can do so by using the Procedure Request API.

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.

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 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 answer, 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.

  • No labels