Advanced questionnaires API workflows

Owned by James Price
Oct 12, 2023
4 min read

Overview

This page outlines the process of retrieving Questionnaire resources, sending questionnaire requests, and retrieving QuestionnaireResponse resources using the new Advanced Questionnaires API endpoints. For more details on each new endpoint, including how they differ from the legacy questionnaire endpoints, see our page on how to use the Advanced Questionnaire API endpoints.

 

Workflow

This diagram outlines the API calls and actions that need to be taken when sending questionnaire requests and retrieving responses, by external systems, PKB APIs, the PKB application and the patient.

Getting a list of Questionnaires

Clinical teams can request that advanced questionnaires be built by PKB, which are added to PKB following testing on Sandbox and approval by the clinical team. Multiple clinical teams can be associated with the same questionnaire and clinical teams can have access to multiple questionnaires.

To see a list of Questionnaire resources that a team has access to, make the following call to the Questionnaire API endpoint.

 curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" “FHIRWALL_URL/Questionnaire/"

  • The authorisation (Bearer) can be retrieved by following the OAuth 2.0 client credentials grant workflow. This then needs to be provided in the header of the API call.

  • X-team-id is the resource ID of the FHIR Organisation resource that represents the PKB clinical team. For now, this will be provided by the PKB Support team. In future, this will be available via an API endpoint. An authorisation token for a system user is a PKB organisation level token. X-team-id therefore needs to be provided to represent the clinical team.

When the above API call is made, a FHIR bundle of Questionnaire resources will be returned. This bundle will contain all of the PKB questionnaires that the clinical team have access to.

 

Triggering a questionnaire

Clinical teams can trigger the sending of a questionnaire request to a patient via an external system, using the $send-questionnaire-request FHIR custom operation. To trigger the sending of a questionnaire, make the following API call:

curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request" --data "{ \"resourceType\":\"Parameters\", \"parameter\":[ { \"name\":\"target\", \"valueReference\":{ \"identifier\":{ \"system\":\"https://fhir.nhs.uk/Id/nhs-number\", \"value\":\"5193233945\" } } }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"12345\" } } ] }"

  • The authorisation (Bearer) can be retrieved by following the OAuth 2.0 client credentials grant workflow. This then needs to be provided in the header of the API call.

  • X-team-id is the resource ID of the FHIR Organisation resource that represents the PKB clinical team. For now, this will be provided by the PKB Support team. In future, this will be available via an API endpoint. An authorisation token for a system user is a PKB organisation-level token. X-team-id therefore needs to be provided to represent the clinical team.

  • Questionnaire ID is the FHIR resource ID of the Questionnaire that is being sent. In the above example, this is bd17e556-20e3-4f01-8078-30e5f675b0f2. This ID can be taken from the relevant Questionnaire resource in the bundle that was returned in the ‘Getting a list of Questionnaires' step of this workflow.

Patient completes questionnaire

When a questionnaire request is sent to a patient, or patients, using the $send-questionnaire-request custom operation, the patient(s) will receive an email notification asking them to complete the questionnaire. The email notification will tell the patient which clinical team has sent the questionnaire and ask them to click a link to complete it.

When the patient clicks the link, they will be asked for their date of birth. This is to confirm they are the intended recipient of the questionnaire, without making the patient log in. If the patient provides the correct date of birth, they are taken to the questionnaire.

As soon as the patient begins answering questions, a QuestionnaireResponse resource is created with a status of ‘in-progress’. This QuestionnaireResponse resource is updated as the patient answers questions. Once the patient submits the questionnaire, the status of the QuestionnaireResponse resource is updated to ‘completed’.

QuestionnaireResponse resources with a status of ‘in-progress’ or ‘completed’ can be retrieved via the QuestionnaireResponse endpoint.

Retrieving a QuestionnaireResponse resource

Clinical teams can retrieve QuestionnaireResponse resources by making API calls to the QuestionnaireResponse API endpoint. QuestionnaireResponses can be searched for by patient, questionnaire ID, or authored (date that the answers were provided).

The below API call is an example of retrieving all QuestionnaireResponse resources for a specific patient.

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/QuestionnaireResponse?patient=Patient/3d8afd18-0844-459a-b3c2-355d02e54c0a"

  • The authorisation (Bearer) can be retrieved by following the OAuth 2.0 client credentials grant workflow. This then needs to be provided in the header of the API call.

  • X-team-id is the resource ID of the FHIR Organisation resource that represents the PKB clinical team. For now, this will be provided by the PKB Support team. In future, this will be available via an API endpoint. An authorisation token for a system user is a PKB organisation-level token. X-team-id therefore needs to be provided to represent the clinical team.

  • The Patient can be searched either using the Patient’s resource ID (as shown in the above API call), or using a supported search parameter on the Patient resource.