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.
...
Endpoint | Method | RequestBody | Auth header |
|---|---|---|---|
https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/questionnaireID/$send-questionnaire-request | POST | parameters: 0..* target 0..1 additionalIdentifier (optional) 0..1 notificaitionFlag (optional)
| Authorization: Bearer <Keycloak token> x-team-id: <UUID> |
...
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’.
Example request URL
| Code Block |
|---|
POST https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request |
...
| Code Block |
|---|
{
"resourceType": "Parameters",
"parameter": [
{
"name": "target",
"valueReference": {
"reference": "Patient/a81e46b1-f953-4599-9721-81e66aa67c34"
}
},
{
"name": "notificationFlag",
"valueCode": "true"
}
]
} |
Example request (raw)
...
]
} |
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
...
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
...
| 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"
}
]
} |
Searching for a Questionnaire resource
...