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

Table of Contents

minLevel	1
maxLevel	6
outline	false
type	list
printable	false

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

Code Block
POST https://iam.sandbox.patientsknowbest.com/auth/realms/pkb/protocol/openid-connect/token

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"

...

Endpoint

Method

RequestBody

Auth header

https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/questionnaireID/$send-questionnaire-request

POST

Parameters Resource

parameters:

0..* target

0..1 additionalIdentifier (optional)

0..1 notificaitionFlag

(optional)

Authorization: Bearer <Keycloak token>

x-team-id: <UUID>

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.

...

The notificationFlag parameter is currently mandatory, but will not serve a function while there is no Practitioner acting as the sender of the questionnaire requestoptional 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

Code Block
POST https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request

Example request header

Authorisation: Bearer aaaaa-bbbbb

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

Example request body

Code Block

{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "target",
            "valueReference": {
                "reference": "Patient/a81e46b1-f953-4599-9721-81e66aa67c34"
            }
        },
        {
            "name": "notificationFlag",
            "valueCode": "true"
        }
    ]
}

...

]
}

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"
            }
         }
     },
        {
            "name": "notificationFlag",
            "valueCode": "true"
        }
    ]
}'
    ]
}'

Differences between the current and new API calls

Current API call for triggering a questionnaire request

curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/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\":\"requestor\", \"valueReference\":{ \"reference\":\"Practitioner/bdaa24d0-3cd5-469c-aa69-db676fa31bbe\" } }, { \"name\":\"notificationFlag\", \"valueCode\":\"EMAIL_NOTIFICATION_DISABLED\" }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"294672281\" } } ] }"

New API call for triggering a questionnaire request

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"
            }
         }
     },
        {
            "name": "notificationFlag",
            "valueCode": "true"
        }
    ]
}'

Summary of the differences

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 still required, but does not control any email notifications. 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 tonow optional and can be used to suppress patient email notifications. It accepts only the value ‘DISABLE_PATIENT_EMAIL_NOTIFICATION’. If this parameter is included with any other value, an error will be returned.

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:

Code Block

{
    "resourceType": "Parameters",
    "parameter": [
{
        "name":"target",
         "valueReference":{
            "identifier":{
               "system":"https://fhir.nhs.uk/Id/nhs-number",
               "value":"5193233945"
            }
         }
     },
        {
            "name": "notificationFlag",
            "valueCode": "true"
        }
    ]
}

Sending a questionnaire to a patient via SMS

...

]
}

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.

Code Block

"extension": [
{
  "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-url",
  "valueString": "https://rc.pkb.io/questionnaire?docId=758413f6-324d-485a-a410-498af8ad19ef&patientId=f47f6c38-7d60-4b7b-8cfc-5b7679da0cff&requesterId=85358fbf-5462-43a9-863b-dbee894407d0&questionnaireTitle=Pre-Surgical%20Health%20Information%20and%20BMI%20Questionnaire"
                    }
                     ]

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.

Code Block

{
    "resourceType": "Parameters",
    "parameter": [
             {
        "name":"target",
         "valueReference":{
            "identifier":{
               "system":"https://fhir.nhs.uk/Id/nhs-number",
               "value":"5193233945"
            }
         }
     },
        {
            "name": "notificationFlag",
            "valueCode": "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.

Searching for a Questionnaire resource

Organisations can retrieve Questionnaire resources using search operations to the Questionnaire endpoint.

...

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.

...

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.

Differences between the current and new API calls

Current API call for searching for a Questionnaire

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/Questionnaire"

New API call for searching for a Questionnaire

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' \

Summary of the differences

X-Org-Public-ID is no longer required as a header. This has been replaced by x-team-id.

Searching for a QuestionnaireResponse resource

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

Code Block
GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse

Example

Retrieving all QuestionnaireResponse resources in a team

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

...

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' \

Differences between the current and new API calls

Current API call for searching for QuestionnaireResponse resources

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "X-Org-Public-Id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "https://sandbox.patientsknowbest.com/fhir/QuestionnaireResponse

New API call for searching for QuestionnaireResponse resources

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' \

Summary of the differences

X-Org-Public-ID is no longer required as a header. This has been replaced by x-team-id

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:

...

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:

Code Block
GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?subject:Patient.identifier=https://fhir.nhs.uk/Id/nhs-number%7CNHS_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:

...

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:

...

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.

...

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

Code Block
GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=2024-01-01&_include=subject

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

Code Block
GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=2024-01-01&_include=source

...

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

Code Block
GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=2024-01-01&_include=based-on

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

Code Block
GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=2024-01-01&_include=subject&_include=based-on

...

Version	Old Version 26	New Version Current
Changes made by	James Price	James Price
Saved on	Sept 26, 2024	Nov 15, 2024

Page Comparison

Versions Compared

Key

Getting a Bearer token

Example request URL

Example request body

Triggering a questionnaire request

OperationDefinition

Example

Example request URL

Example request header

Example request body

Example request (raw)

Differences between the current and new API calls

Current API call for triggering a questionnaire request

New API call for triggering a questionnaire request

Summary of the differences

Triggering using NHS Number

Sending a questionnaire to a patient via SMS

Sending a questionnaire to a patient via SMS

Suppressing an email notification when sending a questionnaire request

Searching for a Questionnaire resource

Example

Differences between the current and new API calls

Current API call for searching for a Questionnaire

New API call for searching for a Questionnaire

Summary of the differences

Searching for a QuestionnaireResponse resource

Example

Retrieving all QuestionnaireResponse resources in a team

Differences between the current and new API calls

Current API call for searching for QuestionnaireResponse resources

New API call for searching for QuestionnaireResponse resources

Summary of the differences

QuestionnaireResponse search parameters

Searching for a QuestionnaireResponse based on subject

Searching for a QuestionnaireResponse using a subject’s national ID

Searching for a QuestionnaireResponse based on completed date

Searching for a QuestionnaireResponse between two dates based on completed date

Searching for a QuestionnaireResponse based on questionnaire

Searching for a QuestionnaireResponse based on status

Searching for a QuestionnaireResponse based on ServiceRequest

Including a Patient or ServiceRequest resource in the response

Including the patient that the questionnaire was sent to

Including the patient that completed the questionnaire

Including the ServiceRequest that was generated when the questionnaire was sent

Including a Patient and a ServiceRequest resource