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 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[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 an email address, given name, family name and date of birth, they will not be sent a questionnaire.  

The notificationFlag parameter is currently mandatory, but will not serve a function while there is no Practitioner acting as the sender of the questionnaire request.

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"
            }
         }
     },
        {
            "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 to.

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:

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.

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.

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

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:

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.

Coming soon: 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 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 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’.

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.