This page contains the specification for the new advanced questionnaires Questionnaire and QuestionnaireResponse 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.

To access the aggregated endpoint, callers will need to be authenticated using OAuth2.0 ‘client credentials’ grant type.

The PKB Sandbox URL is used throughout this page. This should be replaced in your API calls to match the required environment.

Getting a Bearer token

To access the Questionnaire or QuestionnaireResponse endpoints, organisations will need to be authenticated using the OAuth2.0 ‘client credentials' grant type. This can be obtained by providing the client id and client secret in the body of an API call to the token URL.

Example request URL

Example request body

• contentType: application/x-www-form-urlencoded

• client_id: CLIENT ID

• client_secret: CLIENT SECRET

• grant_type: client_credentials

To get a client id and client secret for your organisation, please contact your success PM or the PKB integrations team.

Triggering a questionnaire request

Organisations can use the $send-questionnaire-request custom operation to send questionnaires to patients via our APIs. Immediately following the release of phase 1, this will be the only way to send advanced questionnaires to patients.

This section contains the OperationDefinition of our $send-questionnaire-request custom operation and an example workflow.

OperationDefinition

name

"send-questionnaire-request"

status

"active"

kind

"operation"

description

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.

code

"send-questionnaire-request"

resource

• "Questionnaire"

system

false

type

false

instance

true

parameter

• parameter[0]

  • 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.“

• parameter[1]

  • name = “additionalIdentifier”

  • use = “in”

  • min = 0

  • max = “1”

  • type = “Identifier”

• parameter [2]

  • name = “notificationFlag”

  • use = “in”

  • min = 0

  • max = “1”

• parameter[4]

  • name = ”amendableBy”

  • use = “in”

  • min = 0

  • max = “2”

• parameter[3]

  • name = "request"

  • use = "out"

  • min = 0

  • max = "*"

  • type = "Reference(ServiceRequest)"

Example

This example demonstrates how to trigger a questionnaire request for a specific Patient using the public ID of their Patient resource. Triggering questionnaire requests using NHS numbers is coming soon.  

1. Generate an access token using the client credentials OAuth2.0 grant type, using the PKB access token url and the client id and client secret that have been generated for your PKB Organisation. If you do not have these credentials, please speak to your Success PM.

   1. This example assumes you have been granted an access token of: aaaaa-bbbbb

2. Confirm the ID of the team. You can request this from the PKB support team (available via API in the future).

   1. This example assumes you have a team ID (x-team-id) of: 235a397b-1ae8-4755-9c77-1a0e2fbc5314

3. Confirm the public ID of the patient’s FHIR Patient resource

   1. The example below assumes you have one Patient with the id: a81e46b1-f953-4599-9721-81e66aa67c34

4. Confirm the ID of the Questionnaire

   1. To find the Questionnaire ID of the questionnaire you would like to send, query the Questionnaire endpoint. This will return a bundle of Questionnaire resources that your team has access to (based on the x-team-id in the header of the API call). Take the ID of the Questionnaire resource that you are interested in.

   2. This example assumes a Questionnaire ID of: bd17e556-20e3-4f01-8078-30e5f675b0f2

5. Make the call as detailed below, replacing the access token, x-team-id, Patient ID, and Questionnaire ID with your own values

   1. The questionnaire request will be created and an email will be sent to the patient containing a link to the questionnaire.

   2. If the patient’s PKB record does not have a given name, family name and date of birth, they will not be sent a questionnaire.  

The notificationFlag parameter is optional and can be used to suppress patient email notifications by including it with the value “DISABLE_PATIENT_EMAIL_NOTIFICATION”. If you do not want to disable patient email notifications, do not include the notificationFlag parameter in the API call. If the parameter is included with any value other than “DISABLE_PATIENT_EMAIL_NOTIFICATION”, an error will be returned.

Example request URL

Example request header

Authorisation: Bearer aaaaa-bbbbb

x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314

Example request body

Example request (raw)

curl --location --request POST 'https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/5c69887a-1184-4083-b279-0ff8d634c14b/$send-questionnaire-request' \
--header 'x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314' \
--header 'Authorization: Bearer aaaaa-bbbbb' \
--header 'Content-Type: application/json' \
--data-raw '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "additionalIdentifier",
            "valueIdentifier": {
                "system": "urn:ietf:rfc:4122",
                "value": "urn:uuid:d32f494f-6925-46df-afa4-022df650c1b8"
            }
        },
        {
        "name":"target",
         "valueReference":{
            "identifier":{
               "system":"https://fhir.nhs.uk/Id/nhs-number",
               "value":"9262018118"
            }
         }
     }
    ]
}'

Triggering using NHS Number

To trigger a questionnaire request to a patient using NHS number, replace the FHIR reference in the target field of the API call with an NHS number:

Sending a questionnaire to a patient via SMS

PKB does not currently support SMS notifications for questionnaires. However, the ServiceRequest that is returned when API calls to $send-questionnaire-request are made do contain the questionnaire link that patients see in their email notification. Clinical teams can use their own SMS sending capabilities to invite patients to complete the questionnaire, by creating an SMS using this link and sending it to the patient.

Suppressing an email notification when sending a questionnaire request

Clinical teams can suppress the patient’s email notification when sending a questionnaire request by including the notificationFlag parameter in the API call. When this parameter is included with the value “DISABLE_PATIENT_EMAIL_NOTIFICATION”, the patient will not be sent a PKB email notification.

If you do not want to disable patient email notifications, do not include the notificationFlag parameter in the API call. If the parameter is included with any value other than “DISABLE_PATIENT_EMAIL_NOTIFICATION”, an error will be returned.

Configuring whether a questionnaire can be amended

Clinical teams can configure whether the patient or professionals should be allowed to amend a questionnaire after it has been submitted by including the ‘amendableBy’ parameter. When this parameter is included with the value “Patient”, the patient will be able to amend the questionnaire after they have submitted it. When the ‘amendableBy’ parameter is included with the value “Practitioner”, professionals will be able to amend the answers after the patient has submitted them. If the amendableBy parameter is not included, the patient will not be able to amend the questionnaire after submission. If the amendableBy parameter is included with a value that is not “Patient” or “Practitioner”, an error will be returned.

The ‘amendableBy’ parameter can be included in the API call twice, with “Practitioner” and “Patient”, if the patient and professionals should be allowed to edit the completed questionnaires.

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:

• questionnaireId

Example

This example demonstrates how to search for all Questionnaire resources that a team has access to. The Questionnaire endpoint can also be searched using a specific questionnaireId.

1. Generate an access token using the client credentials OAuth2.0 grant type, using the PKB access token url and the client id and client secret that have been generated for your PKB Organisation. If you do not have these credentials, please speak to your Success PM.

   1. This example assumes you have been granted an access token of: aaaaa-bbbbb

2. Confirm the ID of the team. You can request this from the PKB support team (available via API in the future).

   1. This example assumes you have a team ID (x-team-id) of: 235a397b-1ae8-4755-9c77-1a0e2fbc5314

3. Make the call as detailed below, replacing the access token and x-team-id with your own values.

4. A bundle of Questionnaire resources will be returned

curl --location --request GET 'https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire' \
--header 'x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314' \
--header 'Authorization: Bearer aaaaa-bbbbb' \

To search for a specific questionnaire using its ID, make the following call:

curl --location --request GET 'https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2' \
--header 'x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314' \
--header 'Authorization: Bearer aaaaa-bbbbb' \

This will return the Questionnaire resource with the ID bd17e556-20e3-4f01-8078-30e5f675b0f2, as long as the team represented by the x-team-id is authorised to retrieve it.

Searching for a QuestionnaireResponse resource

Organisations can retrieve all QuestionnaireResponse resources in a team by calling the QuestionnaireResponse endpoint.

Example

Retrieving all QuestionnaireResponse resources in a team

This example demonstrates how to retrieve all questionnaire responses for a specific patient

1. Generate an access token using the client credentials OAuth2.0 grant type, using the PKB access token url and the client id and client secret that have been generated for your PKB Organisation. If you do not have these credentials, please speak to your Success PM.

   1. The example below assumes you have been granted an access token of: aaaaa-bbbbb

2. Confirm the ID of the team. You can request this from the PKB support team (available via API in the future).

   1. This example assumes you have a team ID (x-team-id) of: 235a397b-1ae8-4755-9c77-1a0e2fbc5314

3. Make the call as detailed below, replacing the access token and x-team-id your own values

4. A bundle of QuestionnaireResponse resources will be returned

curl --location --request GET 'https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse' \
--header 'x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314' \
--header 'Authorization: Bearer aaaaa-bbbbb' \

QuestionnaireResponse search parameters

The QuestionnaireResponse endpoint does not currently support search parameters. We support the following search parameters:

• subject

• authored

• based-on

• status

Searching for a QuestionnaireResponse based on subject

The subject field on a QuestionnaireResponse represents the patient that the questionnaire was sent to. To search for all QuestionnaireResponses belonging to a particular patient in your team, include the subject search parameter in your API call to the QuestionnaireResponse endpoint:

The PATIENT_ID in the above example is the patient’s PKB public ID. The above search will return QuestionnaireResponses for the patient with this PKB public ID.

Note: The subject field only represents the patient that the questionnaire was sent to, not the patient that completed the answers. The source field represents the individual that answered the questions. At the moment, source and subject will always be the same. In the future, we will support carers completing questionnaires on behalf of patients. When this happens, the source and subject may be different.

Searching for a QuestionnaireResponse using a subject’s national ID

Organisations that use national IDs (e.g. NHS numbers) to send questionnaires to patients may benefit from searching for QuestionnaireResponses using a patient’s NHS number:

Searching for a QuestionnaireResponse based on completed date

The authored field on a QuestionnaireResponse represents the date and time that the answers were completed by the patient. To search for all QuestionnaireResponse resources for your team from a particular day, include the authored search parameter in your API call to the QuestionnaireResponse endpoint:

The above API call will return QuestionnaireResponses that were completed on 1st January 2024.

Only completed QuestionnaireResponses have an authored field, meaning only completed (and not draft) QuestionnaireResponses will be returned in this search.

Searching for a QuestionnaireResponse between two dates based on completed date

The authored field on a QuestionnaireResponse represents the date and time that the answers were completed by the patient. To search for all QuestionnaireResponse resources for your team between two dates, include the authored search parameter in your API call to the QuestionnaireResponse endpoint:

The above API call will return QuestionnaireResponses that were completed between the 1st January 2024 and the 1st February 2024.

Only completed QuestionnaireResponses have an authored field, meaning only completed (and not draft) QuestionnaireResponses will be returned in this search.

Searching for a QuestionnaireResponse based on questionnaire

To search for QuestionnaireResponse resources that were generated from a particular questionnaire, you can use a chained search on the basedOn field of the QuestionnaireResponse. The basedOn field contains a reference to the ServiceRequest resource that was generated when the questionnaire request was sent to the patient. One of the identifiers on the ServiceRequest represents the questionnaire.

To search for QuestionnaireResponses related to a particular questionnaire, construct a chained search using the based-on search parameter:

QUESTIONNAIRE_ID in the above example is the ID of the questionnaire that is used in the API call to $send-questionnaire-request. The above API call will return QuestionnaireResponses that relate to the questionnaire with this ID.

Note: In previous versions of FHIR, the questionnaire field on a QuestionnaireResponse contained a direct reference to the Questionnaire resource that was sent to the patient. However, this questionnaire field has been replaced in FHIR R4 with a canonical reference, meaning it cannot be used in searches. This is the reason that a chained search on the ServiceRequest is now required.

The field on the QuestionnaireResponse is called basedon, but the search parameter is called based-on. To read more about search parameters, see the FHIR QuestionnaireResponse resource spec.

Searching for a QuestionnaireResponse based on status

To return only QuestionnaireResponses that are complete, include the status search parameter in your API call. This will filter out any QuestionnaireResponses with a status of ‘in-progress’, which have not yet been submitted by the patient.

The above API call will return QuestionnaireResponses that have a status of ‘completed’.

Searching for a QuestionnaireResponse based on ServiceRequest

To search for a specific QuestionnaireResponse using the ID of the ServiceRequest that was generated when the questionnaire was sent, include the based-on search parameter in your API call.

The above API call will return the QuestionnaireResponse that was generated from the ServiceRequest that has the ID in the API call.

Including a Patient or ServiceRequest resource in the response

QuestionnaireResponse resources contain references to FHIR Patient and ServiceRequest resources in the subject, source and basedOn fields. If you need information from these resources that do not appear on the QuestionnaireResponse, such as a patient’s name or NHS number, you can add the _include search parameter to your search.

Multiple _include parameters can be included in one search.

Including the patient that the questionnaire was sent to

The above API call will return all QuestionnaireResponse resources that were submitted on 01-01-2024 and also all of the Patient resources for the patients in the subject field of the QuestionnaireResponse resources.

Including the patient that completed the questionnaire

The above API call will return all QuestionnaireResponse resources that were submitted on 01-01-2024 and also all of the Patient resources for the patients in the source field of the QuestionnaireResponse resources.

Note: At the moment, source and subject will always be the same. In the future, we will support carers completing questionnaires on behalf of patients. When this happens, the source and subject may be different.

Including the ServiceRequest that was generated when the questionnaire was sent

The above API call will return all QuestionnaireResponse resources that were submitted on 01-01-2024 and also all of the ServiceRequest resources that were generated when those questionnaire requests were sent. These ServiceRequest resources are referenced in the basedOn field of the QuestionnaireResponse.

Including a Patient and a ServiceRequest resource

The above API call will return all QuestionnaireResponse resources that were submitted on 01-01-2024, as well as all Patient resources for patients in the subject field and all ServiceRequest resources from the baseOn field of the QuestionnaireResponse resources.