During phase 1 of the rollout of the new advanced questionnaires feature, organisations will only be able to send advanced questionnaires to patients and retrieve the responses via the new advanced questionnaire API endpoints.
This page contains the specification for the new endpoints, as well as examples of API calls that can be made to these endpoints to trigger a questionnaire request, retrieve Questionnaire resources and retrieve QuestionnaireResponse resources.
The advanced questionnaires FHIR resources are in FHIR version 4. This is because Questionnaires and QuestionnaireResponses will be read from our aggregated endpoint.
FHIRWALL_BASE_URL is used throughout this page as a placeholder URL. Since this feature is still in development, the final URL is not yet available. This page will be updated with the correct URL once it is available.
Organisations can use the $send-questionnaire-request custom operation to send questionnaires to patients via our APIs. During phase 1, this will be the only way to send questionnaires to patients.
This section contains the OperationDefinition of our $send-questionnaire-request custom operation and an example workflow.
This operation allows:
a System user to trigger a ServiceRequest to be sent to either specific Patients, or else to all Patients in a specific Organization (PKB clinical team).
The Patient(s) will receive an email containing an invitation to complete the questionnaire. During phase 1, advanced questionnaires cannot be triggered via the UI by patients or professionals and advanced questionnaires will not be visible in patient records.
The response will be made available as a QuestionnaireResponse.
name = "target"
use = "in"
min = 1
max = “500“
type = "Reference(Patient|Organization)"
documentation = “the target references can be either represented as a URL reference or through the use of an identifier representing the national health number. If a target is represented twice, only one request will be created per API call.“
This example assumes you have been granted an access token of: aaaaa-bbbbb
Confirm the ID of the team. You can request this from the PKB support team (available via API in the future).
This example assumes you have a team ID (x-team-id) of: 235a397b-1ae8-4755-9c77-1a0e2fbc5314
Confirm the national ID of the patient
The example below assumes you have one Patient with the following NHS number: 5193233945
If you do not include a national ID, the questionnaire will be sent to every patient in the team represented by the team ID.
Confirm the ID of the Questionnaire
To find the Questionnaire ID of the questionnaire you would like to send, query the Questionnaire endpoint with your teamcode and, optionally, the questionnaire title. This will return a bundle of Questionnaire resources that you have access to. Take the ID of the Questionnaire resource that you are interested in.
This example assumes a Questionnaire ID of: bd17e556-20e3-4f01-8078-30e5f675b0f2
Make the call as detailed below, replacing the access token, x-team-id, NHS number, and Questionnaire ID with your own values
The questionnaire request will be created and an email will be sent to the patient containing a link to the questionnaire.
If the patient’s PKB record does not have an email address, given name, family name and date of birth, they will not be sent a questionnaire. If the request contains more than one NHS number, patients with an email address, given name, family name and date of birth will still receive a questionnaire. The response from the API call will contain the patients that did not receive a questionnaire.
To include an external identifier, which can then be used to retrieve the associated QuestionnaireResponse resources, add the additionalIdentifier parameter shown in the example request body.
Example request URL
requestor/practitioner ID is no longer required. This is because, during phase 1, the questionnaire is not being sent from a specific professional user.
X-Org-Public-ID is replaced by x-team-id in the header. x-team-id is the UUID of the FHIR organisation resource that represents the PKB team. This can be retrieved from the PKB Support team initially, but will soon be available via our APIs.
notificationFlag is no longer required. This is because, during phase 1, the questionnaire is not being sent from a specific professional user and there is therefore nobody for the email notification to go to.
Searching for a Questionnaire resource
Organisations can retrieve Questionnaire resources using search operations to the Questionnaire endpoint.
This section will contain the search parameters that can be used to retrieve Questionnaire resources and an example workflow.
The following search parameters can be used to search for Questionnaire resources:
This example demonstrates how to search for all Questionnaire resources that a team has access to.
Retrieving a QuestionnaireResponse using a business identifier
This example demonstrates how to retrieve a questionnaire response based on a business identifier provided when the questionnaire request was triggered.
When a questionnaire request is triggered, a ServiceRequest is created for each patient that the questionnaire has been sent to. The business identifier, provided when the questionnaire request is triggered, is added to the ServiceRequest resource as an identifier. When the patient completes the questionnaire, the generated QuestionnaireResponse resource contains a basedOn field, which contains a reference to the ServiceRequest. A search can therefore be carried out on this basedOn field to search for QuestionnaireResponse resources based on the additionalId.
Follow the above steps in ‘How to trigger a questionnaire request using national ID’, including the business identifier as the additionalIdentifier in the body of the API call. This example assumes a business identifier of 12345