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

Triggering a Questionnaire Request

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)"

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.