--- title: "Advanced Questionnaires API Specification" canonical: "https://wiki.patientsknowbest.com/space/api/4474372098/Advanced%20Questionnaires%20API%20Specification" format: markdown --- 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](https://wiki.patientsknowbest.com/space/api/3364388935). 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. > Macro (toc) # Getting a Bearer Token > Macro (excerpt) > > To access the Questionnaire or QuestionnaireResponse endpoints, organisations will need to be authenticated using the OAuth2.0 ‘client credentials' grant type. To get authenticated, follow our instructions for [obtaining an aggregated FHIR token](https://wiki.patientsknowbest.com/space/api/4513202208/Obtain+Aggregated+FHIR+token). # Triggering a Questionnaire Request > Macro (excerpt) > > Organisations can use the $send-questionnaire-request custom operation to send questionnaires to patients via our APIs. 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 The Patient(s) will receive an email containing an invitation to complete the questionnaire. 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)" - 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)" > Macro (excerpt) > > | **Endpoint** | **Method** | **RequestBody** | **Auth header** | > | --- | --- | --- | --- | > | [https://aggregated-fhir.sandbox.patientsknowbest.com/fhir](https://aggregated-fhir.rc.pkb.io/fhir/Questionnaire/bd454606-5062-407e-9455-e72b20884ac8/$send-questionnaire-request)/Questionnaire/**questionnaireID**/$send-questionnaire-request | POST | [Parameters Resource](https://build.fhir.org/parameters.html)
parameters:
0..* target
0..1 additionalIdentifier (optional)
0..1 notificationFlag
(optional)
0..2 amendableBy | Authorization: Bearer
x-team-id: | ## Example This example demonstrates how to trigger a questionnaire request for a specific Patient using the public ID of their Patient resource.   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 notifications by including it with the value “DISABLE_PATIENT_NOTIFICATION”. If you do not want to disable patient notifications, do not include the notificationFlag parameter in the API call. If the parameter is included with any value other than “DISABLE_PATIENT_NOTIFICATION”, an error will be returned. ### Example request URL > Macro (excerpt) > > ``` > POST https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request > ``` ### Example request header > Macro (excerpt) > > Authorisation: Bearer **aaaaa-bbbbb** > > x-team-id: **235a397b-1ae8-4755-9c77-1a0e2fbc5314** ### Example request body ``` { "resourceType": "Parameters", "parameter": [ { "name": "target", "valueReference": { "reference": "Patient/a81e46b1-f953-4599-9721-81e66aa67c34" } } ] } ```   ### Example request (raw) > Macro (excerpt) > > > curl --location --request POST '[https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire/5c69887a-1184-4083-b279-0ff8d634c14b/$send-questionnaire-request](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](https://fhir.nhs.uk/Id/nhs-number)", > >                "value":"9262018118" > >             } > >          } > >      } > >     ] > > }' ServiceRequest resources are returned by API calls to $send-questionnaire-request. Please note, the ID on this ServiceRequest is the ID that will belong to the aggregated ServiceRequest. This ID is calculated when the ServiceRequest is returned to you and before the ServiceRequest itself is aggregated. For this reason, the ServiceRequest may not be found via our ServiceRequest endpoint if you search using its ID immediately after making an API call to $send-questionnaire-request. # 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: > Macro (excerpt) > > ``` > { > "resourceType": "Parameters", > "parameter": [ > { > "name":"target", > "valueReference":{ > "identifier":{ > "system":"https://fhir.nhs.uk/Id/nhs-number", > "value":"5193233945" > } > } > } > ] > } > ``` ## Sending a Questionnaire To a Patient via SMS PKB supports SMS notifications for questionnaires in the UK via gov.notify. However, a customer can opt to send SMS themselves via other pathways.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. ``` "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. ``` { "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. ## 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. ``` { "name": "amendableBy", "valueCode": "Practitioner" }, { "name": "amendableBy", "valueCode": "Patient" } ``` # Searching For a Questionnaire Resource > Macro (excerpt) > > 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. > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/Questionnaire > ``` > > The following search parameters can be used to search for Questionnaire resources: > > - questionnaireId ## Example > Macro (excerpt) > > 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](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](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 > Macro (excerpt) > > Organisations can retrieve all QuestionnaireResponse resources in a team by calling the QuestionnaireResponse endpoint. > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse > ``` ## Example ### Retrieving all QuestionnaireResponse resources in a team > Macro (excerpt) > > 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 > Macro (excerpt) > > > curl --location --request GET '[https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse](https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse/0925960d-f123-4926-91e8-57b056fda0ed)' \ > > --header 'x-team-id: **235a397b-1ae8-4755-9c77-1a0e2fbc5314**' \ > > --header 'Authorization: Bearer **aaaaa-bbbbb**' \ ## QuestionnaireResponse Search Parameters > Macro (excerpt) > > The QuestionnaireResponse endpoint supports the following search parameters: > > - subject > - authored > - based-on > - status ### Searching for a QuestionnaireResponse based on subject > Macro (excerpt) > > 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: ``` GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?subject:Patient.identifier=PATIENT_ID ``` 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: > Macro (excerpt) > > ``` > 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 > Macro (excerpt) > > 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: > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=2024-01-01 > ``` > > 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 amended (and not draft) QuestionnaireResponses will be returned in this search. ### Searching for a QuestionnaireResponse between two dates based on completed date > Macro (excerpt) > > 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 *authored* field supports the prefixes *gt (greater than)*, *ge (greater than or equal to), lt (less than), and le (less than or equal to). * > > #### Searching between two dates, excluding the dates in the search > > The gt and lt prefixes can be used to create a search that returns QuestionnaireResponse resources between two dates, **not including **the dates in the search. > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=gt2024-01-01T23:59:59&authored=lt2024-02-01T00:00:00 > ``` > > The above API call will return QuestionnaireResponses that were completed between the 1st January 2024 and the 1st February 2024,** not including **these two dates. > > Please note: the full datetime must be included for searches using the *gt* and *lt* prefixes to ensure the dates included in the search are not returned. This is because of the way FHIR rounds dates that are provided without a time. > > #### Searching between two dates, including dates in the search > > The ge and le prefixes can be used to create a search that returns QuestionnaireResponse resources between two dates, **including **the dates in the search. > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=ge2024-01-01&authored=le2024-02-01 > ``` > > The above API call will return QuestionnaireResponses that were completed between the 1st January 2024 and the 1st February 2024,** including **these two dates. > > 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 > Macro (excerpt) > > To search for QuestionnaireResponse resources that were generated from a particular questionnaire, you can use a the *questionnaire *search parameter. > > To search for QuestionnaireResponses related to a particular questionnaire, construct a search on the *questionnaire* field using the Questionnaire resource’s canonical URL and version number: > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?questionnaire=http://fhir.patientsknowbesst.com/questionnaire/gad-7|1.0 > ``` > > > 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 the search has to be using the canonical URL and version number of the Questionnaire resource and not its ID. ### 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. ``` GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?status=completed ``` The above API call will return QuestionnaireResponses that have a status of ‘completed’. ### Searching for a QuestionnaireResponse based on ServiceRequest > Macro (excerpt) > > 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. > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?based-on=SERVICE-REQUEST-ID > ``` > > 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 > Macro (excerpt) > > 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 > Macro (excerpt) > > ``` > 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 > Macro (excerpt) > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=2024-01-01&_include=source > ``` > > 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 > Macro (excerpt) > > ``` > 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 > Macro (excerpt) > > ``` > GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?authored=2024-01-01&_include=subject&_include=based-on > ``` > > 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. ### Can I link questionnaire requests to an ID in my system (e.g. an appointment ID)? In some workflows, it may be useful to link a specific questionnaire request to a concept in your system. For example, if a questionnaire has been sent to a patient before an appointment, you may want to link the questionnaire request to the appointment in your database. Questionnaire requests are stored in PKB’s database as ServiceRequest resources. When you send a questionnaire request to a patient, a ServiceRequest resource is created. This ServiceRequest resource is returned when you send a questionnaire request to a patient using the $send-questionnaire-request custom operation. An example ServiceRequest is shown below. The relevant ID is in the “id” field and is **09a49ea1-cf82-4494-a99e-f26d8ee5f5df**. This ID is also referenced on the QuestionnaireResponse in the basedOn field. ``` { "resourceType": "Parameters", "parameter": [ { "name": "service-request", "resource": { "resourceType": "ServiceRequest", "id": "09a49ea1-cf82-4494-a99e-f26d8ee5f5df", "meta": { "extension": [ { "url": "ex:createdAt", "valueInstant": "2025-12-18T11:09:01.561265Z" } ], "versionId": "88015", "lastUpdated": "2025-12-18T11:09:01.561265Z", "security": [ { "system": "http://fhir.patientsknowbest.com/codesystem/privacy-label", "code": "GENERAL_HEALTH" }, { "system": "http://fhir.patientsknowbest.com/codesystem/source-organization", "code": "73c1f864-e111-4dda-a7b7-fa366b440330", "display": "AQS source org requester" } ] }, "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/servicerequest-questionnaireRequest", "valueReference": { "reference": "Questionnaire/15fae933-1c18-425d-9ed0-2333dcd259c1", "display": "The Disabilities of the Arm, Shoulder and Hand (DASH)" } }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-control", "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-suppressed", "valueBoolean": false }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-controlled-by", "valueString": "THIRD_PARTY" }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-target-list", "valueString": "[\"PATIENT\"]" } ] }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-url", "valueString": "https://sandbox.patientsknowbest.com/questionnaire?patientId=ff492e50-6286-4459-aedd-22c1a9b4d12f&serviceRequestId=09a49ea1-cf82-4494-a99e-f26d8ee5f5df" } ], "identifier": [ { "system": "http://hl7.org/fhir/R4/questionnaire", "value": "15fae933-1c18-425d-9ed0-2333dcd259c1" } ], "status": "active", "intent": "order", "code": { "text": "Questionnaire" }, "subject": { "reference": "Patient/ff492e50-6286-4459-aedd-22c1a9b4d12f" }, "authoredOn": "2025-12-18T11:09:01+00:00", "requester": { "reference": "Organization/dc67926b-4545-44b1-ab95-e487c6ab431b" }, "performer": [ { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-requester", "valueString": "questionnaire-requester" } ], "reference": "Organization/dc67926b-4545-44b1-ab95-e487c6ab431b" } ] } } ] } ``` If you are using the questionnaire ID in this way, please be aware that if you send the questionnaire to the patient again, there will be a new ServiceRequest generated. This means that if the patient fills out the newly sent questionnaire, their answers will be on a QuestionnaireResponse with the new ServiceRequest ID in the basedOn field. PKB does not currently support reminder notifications about questionnaire requests, but we plan to support these during 2026. ### Searching for QuestionnareResponses using pagination ``` GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?based-on:ServiceRequest.identifier=&_count=10 ``` The _count parameter can be used to paginate the bundle that you get in a response to an API call to the QuestionnaireResponse endpoint. This should be used in cases where you expect lots of responses to your searches, for example if you are retrieving all QuestionnaireResponse resources for a large team, or the full history of a particular patient’s QuestionnaireResponses. In cases where you are still experiencing performance issues while using the _count parameter to paginate the response, you can add _total=0 to the end of your search. This removes the total number of responses from the bundle. Once you reach the final page of the bundle, you will no longer see a ‘next’ field in the QuestionnaireResponse.link. # How to tell how a questionnaire was started A QuestionnaireResponse resource does not have a field which shows the route via which the questionnaire was started (e.g. via API, as a professional via the UI, or by a patient via the UI). However, you can work this out by looking at the *performer* field with the *questionnaire-requester *extension on a ServiceRequest. Add the _include=based-on search parameter to include the ServiceRequests in the response bundle that you get back from the QuestionnaireResponse endpoint. ``` GET https://aggregated-fhir.sandbox.patientsknowbest.com/fhir/QuestionnaireResponse?&_include=based-on ``` Each ServiceRequest resource will have a performer field with a ‘questionnaire-requester’ extension, which contains a reference to the Organization, Practitioner or Patient who started the questionnaire. If the performer is an Organization, this means the questionnaire request was sent by a team via the API. If the performer is a Practitioner, this means the questionnaire request was sent by a professional via the UI. If the performer is a Patient, this means the questionnaire was started by the patient or their carer via the UI.
Example of a ServiceRequest with a Practitioner as the performer Performer field: ``` performer": [ { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-requester", "valueString": "questionnaire-requester" }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/public-id", "valueIdentifier": { "system": "http://fhir.patientsknowbest.com/id/public-id", "value": "37ace448-880e-4dab-badc-40ccac351d69" } } ], "reference": "Practitioner/3e67a317-dd12-3af2-a535-e322f2fa7f3a" } ] ``` Full ServiceRequest ``` { "resourceType": "ServiceRequest", "id": "60a1b891-023a-3e29-8247-506cc34e9d75", "meta": { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/version-persisted", "valueDateTime": "2026-05-28T15:48:10.853+00:00" }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/last-updated-source", "valueString": "forms" }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-last-updated", "valueDateTime": "2026-05-28T15:48:10.886+00:00" }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/access-route", "valueCoding": { "system": "http://fhir.patientsknowbest.com/codesystem/access-route", "code": "FHIR_API", "display": "Integration (FHIR)" } }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-version-id", "valueDecimal": 13016 }, { "url": "ex:createdAt", "valueInstant": "2026-05-28T15:48:13.487580Z" } ], "versionId": "7047150", "lastUpdated": "2026-05-28T15:48:13.487580Z", "security": [ { "system": "http://fhir.patientsknowbest.com/codesystem/privacy-label", "code": "MENTAL_HEALTH" }, { "system": "http://fhir.patientsknowbest.com/codesystem/source-organization", "code": "b155b730-61d6-37b6-88a5-418e3c5fbfec", "display": "AQS source org requester" } ] }, "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/servicerequest-questionnaireRequest", "valueReference": { "reference": "Questionnaire/bef31dd3-c314-3dd0-9443-c470a8d77af7", "display": "Anxiety questionnaire (GAD-7)" } }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-control", "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-suppressed", "valueBoolean": false }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-controlled-by", "valueString": "THIRD_PARTY" }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-target-list", "valueString": "[\"PATIENT\",\"CARER\"]" } ] }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-url", "valueString": "https://rc.pkb.io/questionnaire?patientId=423277de-9e29-4287-8d6c-adee5fed8460&serviceRequestId=949912d6-7885-459d-b012-7b6e0356693d" }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream", "extension": [ { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-source-id", "valueString": "forms" }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-resource-id", "valueString": "ServiceRequest/949912d6-7885-459d-b012-7b6e0356693d" } ] } ], "identifier": [ { "system": "http://hl7.org/fhir/R4/questionnaire", "value": "bef31dd3-c314-3dd0-9443-c470a8d77af7" } ], "status": "active", "intent": "order", "code": { "text": "Questionnaire" }, "subject": { "reference": "Patient/1b76bff2-194c-3561-9d5b-22cf5e0eabd5" }, "authoredOn": "2026-05-28T15:48:10+00:00", "requester": { "reference": "Organization/b155b730-61d6-37b6-88a5-418e3c5fbfec" }, "performer": [ { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-requester", "valueString": "questionnaire-requester" }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/public-id", "valueIdentifier": { "system": "http://fhir.patientsknowbest.com/id/public-id", "value": "37ace448-880e-4dab-badc-40ccac351d69" } } ], "reference": "Practitioner/3e67a317-dd12-3af2-a535-e322f2fa7f3a" } ] } ```
Example of a ServiceRequest with a Patient as the performer Performer field: ``` "performer": [ { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-requester", "valueString": "questionnaire-requester" } ], "reference": "Patient/1b76bff2-194c-3561-9d5b-22cf5e0eabd5" } ``` Full ServiceRequest ``` { "resourceType": "ServiceRequest", "id": "5f312ff9-8344-3dfd-a02a-f3102a4f79ab", "meta": { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/version-persisted", "valueDateTime": "2026-05-28T15:48:46.201+00:00" }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/last-updated-source", "valueString": "forms" }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-last-updated", "valueDateTime": "2026-05-28T15:48:46.201+00:00" }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/access-route", "valueCoding": { "system": "http://fhir.patientsknowbest.com/codesystem/access-route", "code": "FHIR_API", "display": "Integration (FHIR)" } }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-version-id", "valueDecimal": 13026 }, { "url": "ex:createdAt", "valueInstant": "2026-05-28T15:48:47.197254Z" } ], "versionId": "7047161", "lastUpdated": "2026-05-28T15:48:47.197254Z", "security": [ { "system": "http://fhir.patientsknowbest.com/codesystem/privacy-label", "code": "MENTAL_HEALTH" }, { "system": "http://fhir.patientsknowbest.com/codesystem/source-organization", "code": "b155b730-61d6-37b6-88a5-418e3c5fbfec", "display": "AQS source org requester" } ] }, "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/servicerequest-questionnaireRequest", "valueReference": { "reference": "Questionnaire/bef31dd3-c314-3dd0-9443-c470a8d77af7", "display": "Anxiety questionnaire (GAD-7)" } }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-control", "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-suppressed", "valueBoolean": true }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-controlled-by", "valueString": "OUR_CODE" }, { "url": "http://fhir.patientsknowbest.com/structuredefinition/notification-target-list", "valueString": "[]" } ] }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream", "extension": [ { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-source-id", "valueString": "forms" }, { "url": "https://fhir.patientsknowbest.com/structuredefinition/upstream-resource-id", "valueString": "ServiceRequest/51ab8199-866a-4057-8363-2aa63c764526" } ] } ], "identifier": [ { "system": "http://hl7.org/fhir/R4/questionnaire", "value": "bef31dd3-c314-3dd0-9443-c470a8d77af7" } ], "status": "active", "intent": "order", "code": { "text": "Questionnaire" }, "subject": { "reference": "Patient/1b76bff2-194c-3561-9d5b-22cf5e0eabd5" }, "authoredOn": "2026-05-28T15:48:46+00:00", "requester": { "reference": "Organization/b155b730-61d6-37b6-88a5-418e3c5fbfec" }, "performer": [ { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-requester", "valueString": "questionnaire-requester" } ], "reference": "Patient/1b76bff2-194c-3561-9d5b-22cf5e0eabd5" }, { "extension": [ { "url": "http://fhir.patientsknowbest.com/structuredefinition/questionnaire-notification-recipient", "valueString": "questionnaire-notification-recipient" } ], "reference": "Organization/b155b730-61d6-37b6-88a5-418e3c5fbfec" } ] } ```