Versions Compared

Version Old Version 8 New Version 9
Changes made by

James Price

James Price

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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

...

Organisations can use the $send-questionnaire-request custom operation to send questionnaires to patients via our APIs. During Immediately following the release of phase 1, this will be the only way to send advanced questionnaires to patients.

...

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

Endpoint

Method

RequestBody

Auth header

https://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/Questionnaire/questionnaireID/$send-questionnaire-request

POST

Parameters Resource

parameters:

0..* target

0..1 additionalIdentifier (optional)

0..1 notificaitionFlag

 

Authorization: Bearer <Keycloak token>

x-team-id: <UUID>

...

This example demonstrates how to trigger a questionnaire request for a specific Patient using their national IDthe public ID of their Patient resource. Triggering questionnaire requests using NHS numbers is coming soon.  

  1. Generate an access token by following the OAuth 2.0 walkthroughusing 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 national public ID of the patientpatient’s FHIR Patient resource

    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.

    3. 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 with your teamcode and, optionally, the questionnaire title. This will return a bundle of Questionnaire resources that you have your team has access to . Take the ID (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, NHS numberPatient 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. 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.

 

...

    1.  

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

Code Block
POST https://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/Questionnaire/questionnaireId/$sendbd17e556-questionnaire-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request

Example request header

...

Example request body

Code Block
{
 	   "resourceType": "Parameters",
    	"parameter": [
		{
			
        {
            "name": "target",
			"valueReference": {
				"identifier            "valueReference": {
				"system
                "reference": "https://fhir.nhs.uk/Id/nhs-number",
				"value": "5193233945"} 
			}
		},
		{
			Patient/a81e46b1-f953-4599-9721-81e66aa67c34"
            }
        },
        {
            "name": "additionalIdentifiernotificationFlag",
 			"valueIdentifier": {
			"system": "https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest",
			"value           "valueCode": "12345true"
			}
		}
	        }
    ]
}

 

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_URLhttps://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request" --data "{ \"resourceType\":\"Parameters\", \"parameter\":[ { \"name\":\"target\", \"valueReference\":{ \"identifierreference\": \”Patient/a81e46b1-f953-4599-9721-81e66aa67c34”\: } ,{\"systemname\":\"notificationFlag\"https://fhir.nhs.uk/Id/nhs-number\", \"value, \"valueCode\":\"5193233945”True”\ " ] } } }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"

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://fhir-opensandbox.cernerpatientsknowbest.com/fhir/r4Questionnaire/ec2458f2bd17e556-1e2420e3-41c84f01-b71b8078-0e701af7583d/ServiceRequest30e5f675b0f2/$send-questionnaire-request" --data "{ \"resourceType\":\"Parameters\", \"valueparameter\":[ { \"name\":\"12345target\" } } ] }"

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, \"valueReference\":{ \"identifier\":{ \"system\":\"https://fhir.nhs.uk/Id/nhs-number\", \"value\":\"Parameters5193233945\" , \"parameter\":[ } } }, { \"name\":\"targetrequestor\", \"valueReference\":{ \"identifierreference\":{ \"system\":\"https://fhir.nhs.uk/Id/nhs-number\", \"valuePractitioner/bdaa24d0-3cd5-469c-aa69-db676fa31bbe\" } }, { \"name\":\"5193233945notificationFlag\" } } }, { \"namevalueCode\":\"requestor\", \"valueReference\":{ \"reference\":\"Practitioner/bdaa24d0-3cd5-469c-aa69-db676fa31bbe\" } }, { \"name\":\"notificationFlag\", \"valueCode\":\"EMAILEMAIL_NOTIFICATION_DISABLED\" }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"294672281\" } } ] }"

...

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” "https://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/Questionnaire/bd17e556-20e3-4f01-8078-30e5f675b0f2/$send-questionnaire-request" --data "{ \"resourceType\":\"Parameters\", \"parameter\":[ { \"name\":\"target\", \"valueReference\":{ \"identifierreference\": { \"system\":\"https://fhir.nhs.uk/Id/nhs-number\", \"value\":\"5193233945\" } } }\”Patient/a81e46b1-f953-4599-9721-81e66aa67c34”\: } ,{\"name\":\"additionalIdentifiernotificationFlag\", \"valueIdentifiervalueCode\":{ \"system”True”\ ":\"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 requiredstill 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.

...

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

  • title

  • questionnaireId 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 by following the OAuth 2.0 walkthrough

    1. This example assumes you have been granted an access token of: aaaaa-bbbbb

    Confirm the ID of the team. 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 -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx aaaaa-bbbbb" --header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" “https://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/Questionnaire/"

Differences between the current and new API calls

Current API call for searching for a Questionnaire

...

To search for a specific questionnaire using its ID, make the following call:

 curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx aaaaa-bbbbb" --header "Xx-Orgteam-Public-Idid: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" "“https://aggregated-fhir.sandbox.patientsknowbestpatietnsknowbest.com/fhir/Questionnaire"

...

/bd17e556-20e3-4f01-8078-30e5f675b0f2"

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 curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" --header "xX-Org-teamPublic-idId: 235a397b-1ae8-4755-9c77-1a0e2fbc5314" “"https://aggregated-fhir.sandbox.patietnsknowbestpatientsknowbest.com/fhir/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.

Code Block
GET https://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/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

...

New API call for searching for a Questionnaire

 curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer aaaaa-bbbbb" --header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314” " “https://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/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.

...

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

...

.patietnsknowbest.com/fhir/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 all QuestionnaireResponse resources in a team by calling the QuestionnaireResponse endpoint.

Code Block
GET https://aggregated-fhir.sandbox.patietnsknowbest.com/fhir/QuestionnaireResponse

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: eyJhbGxxxx 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 Questionnaire reference

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

  4. Confirm the business identifier

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

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

  6. A bundle of QuestionnaireResponse resources will be returned

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

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

New API call for searching for QuestionnaireResponse resources

...

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

Summary of the differences

...