Versions Compared

Version Old Version 2 New Version 3
Changes made by

James Price

James Price

Saved on

Key

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

...

Endpoint

Method

RequestBody

Auth header

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

POST

Parameters Resource

parameters:

1..1 teamId

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 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, Team IDx-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.

...

Authorisation: Bearer aaaaa-bbbbb

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

Example request body

Code Block
{
	"resourceType": "Parameters",
	"parameter": [
		{
			"name": "teamIdtarget",
			"valueStringvalueReference": "235a397b-1ae8-4755-9c77-1a0e2fbc5314"{
		},
		{
			"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"
			}
		}
	]
}

...

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\":\"teamId\", \"valueString\":{\“235a397b-1ae8-4755-9c77-1a0e2fbc5314\”} }, { \"name\":\"additionalIdentifier\", \"valueIdentifier\":{ \"system\":\"https://fhir-open.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/ServiceRequest\", \"value\":\"12345\" } } ] }"

...

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

...

  • 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 no longer required as a header. This is because the organisaton can now be derived from the authorisation token, due to changes in the way the advanced questionnaire APIs handle authorisationreplaced 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.

  • teamId is now required.

Searching for a Questionnaire resource

...

  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 of: 235a397b-1ae8-4755-9c77-1a0e2fbc5314

  3. Make the call as detailed below, replacing the access token and teamId with your own values.

  4. A bundle of Questionnaire resources will be returned

curl  curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" "FHIRWALL_URL/Questionnaire/?teamId=--header "x-team-id: 235a397b-1ae8-4755-9c77-1a0e2fbc5314"

...

“FHIRWALL_URL/Questionnaire/"

Differences between the current and new API calls

...

New API call for searching for a Questionnaire

curl  curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" "FHIRWALL_URL/Questionnaire/?teamId=--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 is because the organisaton can now be derived from the authorisation token, due to changes in the way the advanced questionnaire APIs handle authorisation.

  • teamId is now required as a search parameter.

  • Since teamId is required as a search parameter, the API call is a search operation and not a read operation. This means, even if only one Questionnaire is found, a FHIR bundle containing the one Questionnaire resource will be returned.

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.

...

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

Organisations will need to provide teamId when searching for Questionnaire resources.

...

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

...

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

...

curl -X GET --header "Accept: application/fhir+json" --header "Authorization: Bearer eyJhbGxxxx" "FHIRWALL_URL/QuestionnaireResponse?teamId=--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 is because the organisaton can now be derived from the authorisation token, due to changes in the way the advanced questionnaire APIs handle authorisation.

...

teamId is now required as a search parameter.

...

differences

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