Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

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

FHIRWALL_BASE_URL is used throughout this page as a placeholder URL. Since this feature is still in development, the final URL is not yet available. This page will be updated with the correct URL once it is available.

Triggering a questionnaire request

Organisations can use the $send-questionnaire-request custom operation to send questionnaires to patients via our APIs. During phase 1, this will be the only way to send 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 = "request"

    • use = "out"

    • min = 0

    • max = "*"

    • type = "Reference(ServiceRequest)"

Endpoint

Method

RequestBody

Auth header

FHIRWALL_BASE_URL/Questionnaire/questionnaireID/$send-questionnaire-request

POST

Parameters Resource

parameters:

0..* target

0..1 additionalIdentifier

 

Authorization: Bearer <Keycloak token>

x-team-id: <UUID>

Example

This example demonstrates how to trigger a questionnaire request for a specific Patient using their national ID. 

  1. Generate an access token by following the OAuth 2.0 walkthrough

    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 national ID of the patient

    1. The example below assumes you have one Patient with the following NHS number: 5193233945

    2. If you do not include a national ID, the questionnaire will be sent to every patient in the team represented by the team ID.

  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 with your teamcode and, optionally, the questionnaire title. This will return a bundle of Questionnaire resources that you have access to. 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, NHS number, 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. If the request contains more than one NHS number, patients with an email address, given name, family name and date of birth will still receive a questionnaire. The response from the API call will contain the patients that did not receive a questionnaire.

 

To include an external identifier, which can then be used to retrieve the associated QuestionnaireResponse resources, add the additionalIdentifier parameter shown in the example request body.

Example request URL

POST FHIRWALL_BASE_URL/Questionnaire/questionnaireId/$send-questionnaire-request

Example request header

Authorisation: Bearer aaaaa-bbbbb

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

Example request body 

{
	"resourceType": "Parameters",
	"parameter": [
		{
			"name": "target",
			"valueReference": {
				"identifier": {
				"system": "https://fhir.nhs.uk/Id/nhs-number",
				"value": "5193233945"} 
			}
		},
		{
			"name": "additionalIdentifier", 
			"valueIdentifier": {
			"system": "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest",
			"value": "12345"
			}
		}
	]
}

 

Example request (raw)

curl -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/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\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"12345\" } } ] }"

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 -X POST --header "Accept: application/fhir+json" --header "Content-Type: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/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\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"12345\" } } ] }"

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 no longer required. 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.

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. 

GET [baseURL]/Questionnaire

The following search parameters can be used to search for Questionnaire resources:

  • title

  • questionnaireId

Example

This example demonstrates how to search for all Questionnaire resources that a team has access to.

  1. Generate an access token by following the OAuth 2.0 walkthrough

    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 -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" “FHIRWALL_URL/Questionnaire/"

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 -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" “FHIRWALL_URL/Questionnaire/"

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 QuestionnaireResponse resources based on patient, additionalId, questionnaireId and date, using search operations to the QuestionnaireResponse endpoint.

This section will contain the search parameters that can be used to retrieve QuestionnaireResponse resources and an example workflow. 

GET [baseURL]/QuestionnaireResponse

The following search parameters can be used to search for QuestionnaireResponse resources:

  • subject

  • questionnaireId

  • authored

Example

Retrieving all QuestionnaireResponse resources for a specific patient

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

  1. Generate an access token by following the OAuth 2.0 walkthrough

    1. The example below assumes you have been granted an access token of: eyJhbGxxxx

  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 Patient’s NHS number

    1. The example below assumes a patient with a Patient resource ID of 3d8afd18-0844-459a-b3c2-355d02e54c0a

  4. Make the call as detailed below, replacing the access token, x-team-id and search parameters with your own values

  5. A bundle of QuestionnaireResponse resources will be returned

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/QuestionnaireResponse?patient=Patient/3d8afd18-0844-459a-b3c2-355d02e54c0a"

Retrieving a QuestionnaireResponse using a business identifier

This example demonstrates how to retrieve a questionnaire response based on a business identifier provided when the questionnaire request was triggered.

When a questionnaire request is triggered, a ServiceRequest is created for each patient that the questionnaire has been sent to. The business identifier, provided when the questionnaire request is triggered, is added to the ServiceRequest resource as an identifier. When the patient completes the questionnaire, the generated QuestionnaireResponse resource contains a basedOn field, which contains a reference to the ServiceRequest. A search can therefore be carried out on this basedOn field to search for QuestionnaireResponse resources based on the additionalId.

  1. Follow the above steps in ‘How to trigger a questionnaire request using national ID’, including the business identifier as the additionalIdentifier in the body of the API call. This example assumes a business identifier of 12345

  2. Generate an access token by following the OAuth 2.0 walkthrough

    1. The example below assumes you have been granted an access token of: eyJhbGxxxx

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

  4. Confirm the Questionnaire reference

    1. The example below assumes a reference of: Questionnaire/f1a841f1-6f3a-43fc-830f-e1417b4ff13d

  5. Confirm the business identifier

    1. The business identifier in this example was set in step 1 as 12345

  6. Make the call as detailed below, replacing the access token, x-team-id, and search parameters with your own

  7. A bundle of QuestionnaireResponse resources will be returned

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/QuestionnaireResponse?based-on:ServiceRequest.identifier=https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest%7C12345&_include=QuestionnaireResponse:basedOn:ServiceRequest"

Differences between the current and new API calls

Current API call for searching for QuestionnaireResponse resources for a specific patient

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?patient=Patient/3d8afd18-0844-459a-b3c2-355d02e54c0a"

New API call for searching for QuestionnaireResponse resources for a specific patient

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header “x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” "FHIRWALL_URL/QuestionnaireResponse?patient=Patient/3d8afd18-0844-459a-b3c2-355d02e54c0a"

Summary of the differences

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

  • No labels