{"openapi":"3.0.3","info":{"title":"Wayfinder - National Questionnaires API","description":"## Overview\n\nThis API provides: \n- A list of questionnaire templates for a patient context\n- A way to submit completed questionnaires for a patient\n- A way to retrieve submitted questionnaire responses for a patient    \n\nIf you are interested in using this API in another context, [contact us](https://digital.nhs.uk/developer/help-and-support).\n\n## API status\nThis API is [in production, beta but internal](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning the API is not currently available for integration by external third parties. If you want to use it, [contact us](https://digital.nhs.uk/developer/help-and-support) and we'll look at making it available.\n    \nIf you would still like to be involved in our beta programme or use this API, [contact us](https://digital.nhs.uk/developer/help-and-support).\n    \n## Service level\nThis API is a silver service, meaning it is operational 24 hours a day, 365 days a year but only supported during working hours.\n\nFor more details, see [service levels](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#service-levels).\n\n## Technology\nThis API is [RESTful](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).\n\nIt conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir)\nglobal standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/),\nexcept that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.\n\nIt includes some country-specific FHIR extensions, which have been built against [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core).\n\nYou do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.\nIn particular:\n- resource names are capitalised and singular, for example `/QuestionnaireResponse` or `/Questionnaire` not `/questionnaire-responses` or `/questionnaires`\n- array names are singular, for example `entry` not `entries` for FHIR bundle entries\n- data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object\n\nThere are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration.\n\nYou must adhere to the following requirements when integrating to the Wayfinder - National Questionnaires API.\n\n| Requirement Reference | Quality attribute(s)                                 | Requirement                           | MoSCoW  |\n|-----------------------|------------------------------------------------------|---------------------------------------|---------|\n| WF-NFR-01             | Performance                                          | **Response times**<br>API requests for appointments and referrals must return a response with patient data within 1,000ms at 95th percentile (P95).<br>API requests for wait times must return a response within 600ms at 95th percentile (P95)                        | M/S     |\n| WF-NFR-02             | Performance                                          | **Timeouts**<br>The API must respond with a HTTP 504 'Gateway Timeout' after 10,000 ms have expired<br>*Note* that calls to ODS and e-RS  Healthcare Services APIs time out after 30,000 ms                              | M       |\n| WF-NFR-03             | Availability                                         | **Throttling**<br>The API must limit requests and respond with a HTTP 429 'Too Many Requests' response at 25 TPS (transactions per second)<br>*Note* the 25 TPS rate limit applies to each API that the Patient Care Aggregator provides for the NHS App, including the API for the retrieval of appointment and referrals, as well as the API to retrieve wait times.                            | M       |\n| WF-NFR-04             | Reliability                                          | **Data timeliness**<br>N/A                       | M       |\n| WF-NFR-05             | Availability                                         | **Service availability**<br>The Aggregator will provide Silver+ (99.5%) availability under NHS guidelines<br>See [Cloud security - good practice guide](https://digital.nhs.uk/services/cloud-centre-of-excellence/cloud-security-good-practice-guide/9.-appendix-b-service-classifications)                  | M       |\n| WF-NFR-06             | Availability<br>Reliability<br>Evolvability          | **Releases & Maintenance**<br>Sprint cadence of 2 weeks with at least one release by the end of each sprint<br>During maintenace windows (max 2hrs) API must respond with HTTP 503 Service Unavailable                | M       |\n| WF-NFR-07             | Usability                                            | **No content for user**<br>Respond with HTTP 200 'OK' status code with an empty body if no data was retrieved and there were no upstream errors.<br>This applies to all APIs published by the Patient Care Aggregator.                   | M       |\n| WF-NFR-09             | Observability<br>Security<br>Information governance  | **Logging and alerting**<br>All logs must be shipped into NHSE's preferred logging tools and/or dashboards.<br>All requests must be clearly tracable.<br>Errors must generate alarms against NHSE agreed thresholds.<br>Alarms must not be raised for errors against maintenance responses.<br>Clinical and personal identifiable data must be omitted from production logs.<br>`X-Correlation-ID` must be propagated to e-RS and all Portal systems, and all transactional log events that contain X-Correlation-ID must be retained for 90 days.                  | M       |\n| WF-NFR-10             | Testability                                          | **Contract testing**<br>A range of contract tests for all integrated parties against the full range of API requests must be included in the build pipeline job for any Aggregator changes.                      | M       |\n| WF-NFR-11             | Performance                                          | **Volumetrics**<br>Close tracking of the following is required for BETA period:<br>- Transactions per second<br>- Requests to Aggregator (unique/returning)<br>- Requests to e-RS (unique/returning)<br>- Requests to Portal (unique/returning)<br>- Errors (by type)                           | M       |\n| WF-NFR-12             | Cost<br>Security<br>Interoperability                 | **Hosting**<br>The Aggregator must be hosted on NHS Digital's Cloud.<br>Access to all its APIs must be controlled via the NHSE's API Platform (https://digital.nhs.uk/services/api-platform)                               | M       |\n| WF-NFR-13             | Serviceability                                       | **Operations**<br>Commitment of operational response against Silver+ (99.5%) availability under NHS guidelines.<br>See [Cloud security - good practice guide](https://digital.nhs.uk/services/cloud-centre-of-excellence/cloud-security-good-practice-guide/9.-appendix-b-service-classifications)<br>This will require on-call DevOps escalation for outages                            | M       |\n| WF-NFR-14             | Security                                             | **Authentication**<br>**Patient authentication**<br>- The Aggregator must expose all its public endpoints via the NHSE's API Platform (https://digital.nhs.uk/services/api-platform) and utilise the NHS login's ID token for authentication of patients.<br>- The NHS login' ID token provided in requests from the NHS App will be passed to all downstream calls to NHS e-RS and the Portal system.<br>- Checking of NHS login's identity proofing level (e.g. P9) will not be carried out in the Aggregator.<br><br>**System authentication**<br>- Calls to Portal systems' APIs must utilise OAuth 2.0 Client Credentials Flow pattern.                        | M       |\n| WF-NFR-15             | Information governance                               | **User data revocation or request**<br>N/A       | M       |\n| WF-NFR-16             | Information governance<br>Clinical safety            | **Age restriction**<br>Any request from a patient younger than 16 years of age must be responded to with HTTP 403 'Forbidden' status code with clear indication that the patient is under the minimum age limit.                       | M       |\n| WF-NFR-17             | Security<br>Information governance                   | **Access to personal identifiable data**<br>All user requests to the Aggregator must be logged and audited. Personal identifiable data must not be recorded in production or any other logs<br>Any access to personal identifiable data in the Aggregator must be limited to the security cleared staff.<br>Access to AWS services that hold personal identifiable data must be managed by NHSE and its security controls  | M       |\n| WF-NFR-18             | Security<br>Clinical safety                          | **Inactivity timeouts**<br>N/A                   | M       |\n\n## Network access\nThis API is available on the internet and, indirectly, on the [Health and Social Care Network (HSCN)](https://digital.nhs.uk/services/health-and-social-care-network).\n\nFor more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).\n\n## Security and authorisation\nThis API is [user-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis), meaning an end user must be present, authenticated and authorised.\n\nThe end user must be:\n* a patient who receives health and social care or makes use of NHS services\n* strongly authenticated, using [NHS login](https://digital.nhs.uk/services/nhs-login)\n\nTo use this API, use the following security pattern:\n\n|Security pattern                                                                                                                                                                                                               |Technical details                                    |Advantages                                                   | Disadvantages                                           |\n|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------| ------------------------------------------------------------|---------------------------------------------------------|\n|[NHS login - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation) |OAuth 2.0 token exchange with signed JWT             |Gives access to user information.                            |Need to integrate and onboard separately with NHS login. |\n\n## Environments and testing\n| Environment       | Base URL                                                                                              | Linked NHS login environment  |\n| ----------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------- |\n| Sandbox           | `https://sandbox.api.service.nhs.uk/questionnaires`                 | Not applicable                |\n| Integration test  | `https://int.api.service.nhs.uk/questionnaires`                     | NHS login - integration (AOS) |\n| Production        | `https://api.service.nhs.uk/questionnaires`                         | NHS login - Live (production) |\n\n### Sandbox testing\nOur sandbox environment:\n* is for early testing\n* is [open-access](https://digital.nhs.uk/developer/guides-and-documentation/testing#open-access-testing) — no authorisation required\n* returns pre-canned responses that match the examples in this specification\n* is stateless — it does not persist any data\n\nFor more details on sandbox testing, see [sandbox testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing).\n\n### Integration testing\nOur [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):\n* is for formal integration testing\n* includes authorisation\n\nIt is an end-to-end environment - linked to the Integration (AOS) instance of NHS login.\n\n- For more details on integration testing, see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).\n\n## Onboarding\n- You need to get your software approved by us before it can go live with this API. We call this onboarding. The onboarding process can sometimes be quite long, so it's worth planning well ahead.\n\n- To onboard for this API, follow the [Supplier Conformance Assessment List (SCAL)](https://digital.nhs.uk/developer/guides-and-documentation/onboarding-process#onboard-using-the-supplier-conformance-assessment-list-scal-process) process.\n\n- To get started with the SCAL process for this API, [contact us](https://digital.nhs.uk/developer/help-and-support).\n\n## Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n* 400 to 499 if it failed because of a client error by your application\n* 500 to 599 if it failed because of an error on our server\n\nErrors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n","contact":{"name":"questionnaires API Support","url":"https://digital.nhs.uk/developer/help-and-support","email":"api.management@nhs.net"},"version":"v1.0.0"},"servers":[{"url":"https://sandbox.api.service.nhs.uk/questionnaires","description":"Sandbox environment"},{"url":"https://int.api.service.nhs.uk/questionnaires","description":"Integration environment (AOS)"},{"url":"https://api.service.nhs.uk/questionnaires","description":"Production environment"}],"paths":{"/auth/token":{"post":{"tags":["Authentication"],"summary":"Exchange authorisation code for session details and id_token","description":"This endpoint exchanges an authorisation_code for user session details and an id_token for authentication in the UI app. This is not a FHIR endpoint.\n","parameters":[{"$ref":"#/components/parameters/Authorization"},{"$ref":"#/components/parameters/xCorrelationId"}],"requestBody":{"content":{"application/json":{"schema":{"required":["authorisation_code"],"type":"object","properties":{"authorisation_code":{"type":"string","description":"The authorisation code received from NHS login or similar provider."}}},"examples":{"example":{"summary":"Example request","value":{"authorisation_code":"abc123"}}}}},"required":true},"responses":{"200":{"description":"Successfully exchanged code for session details and id_token.","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/json":{"schema":{"required":["id_token","user_id","expires_in"],"type":"object","properties":{"id_token":{"type":"string","description":"JWT token for user authentication."},"user_id":{"type":"string","description":"Unique identifier for the user."},"expires_in":{"type":"integer","description":"Token expiry in seconds."},"session_details":{"type":"object","description":"Additional session details for UI app."}}},"examples":{"example":{"summary":"Example response","value":{"id_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","user_id":"user-123","expires_in":3600,"session_details":{"name":"Jane Doe","email":"jane.doe@example.com"}}}}}}},"400":{"description":"Bad request - missing or invalid authorisation_code.","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Missing authorisation_code"}}}}}},"401":{"description":"Unauthorized - authentication failed.","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid credentials"}}}}}},"500":{"description":"Internal server error.","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}},"deprecated":false}},"/FHIR/R4/Questionnaire":{"get":{"tags":["Questionnaires"],"summary":"Retrieves a list of questionnaires for a treatment function and organisation.","description":"Returns a FHIR `Bundle` of `Questionnaire` resources.\n\nRequired filters:\n- `_tag` for treatment function code\n- `context` for ODS organisation code\n","operationId":"get-questionnaires","parameters":[{"$ref":"#/components/parameters/Authorization"},{"$ref":"#/components/parameters/tag"},{"$ref":"#/components/parameters/context"},{"$ref":"#/components/parameters/xCorrelationId"},{"$ref":"#/components/parameters/nhsdIdToken"}],"responses":{"200":{"$ref":"#/components/responses/SuccessQuestionnaire"},"400":{"$ref":"#/components/responses/BadRequestQuestionnaire"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"deprecated":false,"security":[{"nhs-login-p9":[]}]}},"/FHIR/R4/QuestionnaireResponse":{"get":{"tags":["Questionnaire Responses"],"summary":"Retrieves a list of questionnaire responses for a given patient.","description":"The Questionnaire Response API will return a FHIR [Bundle](https://www.hl7.org/fhir/r4/bundle.html) resource, containing multiple [QuestionnaireResponse](https://www.hl7.org/fhir/r4/questionnaireresponse.html) resources (based on the UK Core FHIR specification) for use by the NHS App to the following specification.\n\nUse this endpoint to get a list of questionnaire responses for a given patient.\n\nThe endpoint returns the list as a FHIR 'bundle' which consists of questionnaire responses.\n\nIf no questionnaire responses were found for the given patient, and there were no errors, the endpoint returns an empty FHIR bundle.\n","operationId":"get-questionnaire-responses","parameters":[{"$ref":"#/components/parameters/Authorization"},{"$ref":"#/components/parameters/subjectIdentifier"},{"$ref":"#/components/parameters/sourceIdentifier"},{"$ref":"#/components/parameters/tag"},{"$ref":"#/components/parameters/xCorrelationId"},{"$ref":"#/components/parameters/nhsdIdToken"},{"$ref":"#/components/parameters/elements"}],"responses":{"200":{"$ref":"#/components/responses/Success"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"deprecated":false,"security":[{"nhs-login-p9":[]}]},"post":{"tags":["Questionnaire Responses"],"summary":"Creates a questionnaire response for a patient.","description":"The Questionnaire Response API validates and creates a FHIR [QuestionnaireResponse](https://www.hl7.org/fhir/r4/questionnaireresponse.html) resource.","operationId":"create-questionnaire-responses","parameters":[{"$ref":"#/components/parameters/Authorization"},{"$ref":"#/components/parameters/xCorrelationId"},{"$ref":"#/components/parameters/nhsdIdToken"}],"requestBody":{"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/QuestionnaireResponse"},"examples":{"questionnaireResponseCreateRequest":{"$ref":"#/components/examples/questionnaireResponseCreateRequest"}}}},"required":true},"responses":{"202":{"description":"QuestionnaireResponse accepted successfully.","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/QuestionnaireResponseAcceptedResponse"},"examples":{"questionnaireResponseAcceptedResponse":{"$ref":"#/components/examples/questionnaireResponseAcceptedResponse"}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"deprecated":false}}},"components":{"schemas":{"Questionnaire":{"required":["resourceType","id","title","version","status","date","publisher","meta","useContext","item"],"type":"object","properties":{"resourceType":{"enum":["Questionnaire"],"type":"string"},"id":{"type":"string","example":"44cad113-50ba-4b7e-9d46-c067876417c5"},"title":{"type":"string","example":"National PIFU Question - 301 RTK"},"version":{"type":"string","example":"1.0"},"status":{"enum":["active","draft","retired","unknown"],"type":"string","example":"active"},"date":{"type":"string","format":"date","example":"2025-01-10"},"publisher":{"type":"string","example":"NHS England"},"meta":{"type":"object","properties":{"profile":{"type":"array","items":{"type":"string","format":"uri"}},"tag":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","format":"uri"},"code":{"type":"string"}}}}}},"useContext":{"type":"array","items":{"type":"object","properties":{"code":{"type":"object","properties":{"system":{"type":"string","format":"uri"},"code":{"type":"string"}}},"valueCodeableConcept":{"type":"object","properties":{"coding":{"type":"array","items":{"type":"object","properties":{"system":{"type":"string","format":"uri"},"code":{"type":"string"}}}}}}}}},"item":{"type":"array","items":{"$ref":"#/components/schemas/QuestionnaireItem"}}},"description":"A FHIR Questionnaire resource."},"QuestionnaireItem":{"required":["linkId","text","type"],"type":"object","properties":{"linkId":{"type":"string"},"text":{"type":"string"},"type":{"enum":["group","display","coding"],"type":"string"},"repeats":{"type":"boolean"},"required":{"type":"boolean"},"item":{"type":"array","items":{"$ref":"#/components/schemas/QuestionnaireItem"}},"answerOption":{"type":"array","items":{"type":"object","properties":{"valueCoding":{"$ref":"#/components/schemas/QRCoding"}}}}}},"QuestionnaireResponseAcceptedResponse":{"allOf":[{"$ref":"#/components/schemas/QuestionnaireResponse"},{"required":["id"],"type":"object","properties":{"id":{"type":"string","description":"Identifier assigned to the created QuestionnaireResponse.","example":"c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"}}}]},"QuestionnaireResponse":{"required":["resourceType","basedOn","questionnaire","status","subject","source","meta","authored","item","extension"],"type":"object","properties":{"resourceType":{"enum":["QuestionnaireResponse"],"type":"string","description":"FHIR resource type"},"basedOn":{"type":"array","items":{"required":["type","identifier"],"type":"object","properties":{"type":{"type":"string","example":"CarePlan"},"identifier":{"$ref":"#/components/schemas/QRIdentifier"}}},"description":"Plan/proposal/order fulfilled by this questionnaire response"},"questionnaire":{"type":"string","description":"The associated Questionnaire that is being answered","format":"uri","example":"https://api.service.nhs.uk/questionnaires/FHIR/R4/Questionnaire/36321f2e-103c-41a8-9f4d-90d39cd925d3"},"status":{"enum":["in-progress","completed","amended","entered-in-error","stopped"],"type":"string","description":"The position of the questionnaire response within its overall lifecycle"},"subject":{"required":["type","identifier"],"type":"object","properties":{"type":{"type":"string","example":"Patient"},"identifier":{"$ref":"#/components/schemas/QRIdentifier"}},"description":"The subject of the questions"},"source":{"required":["identifier"],"type":"object","properties":{"identifier":{"$ref":"#/components/schemas/QRIdentifier"}},"description":"The individual or organisation associated to the Questionnaire Response."},"meta":{"type":"object","properties":{"tag":{"type":"array","items":{"required":["system","code"],"type":"object","properties":{"system":{"type":"string","description":"Identity of the terminology system","format":"uri","example":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-treatment-function"},"code":{"type":"string","description":"Symbol in syntax defined by the system","example":100},"display":{"type":"string","description":"Representation defined by the system"}}},"description":"Tags applied to this resource"}},"description":"Metadata about the resource"},"authored":{"type":"string","description":"Date the answers were gathered","format":"date-time","example":"2025-01-16 15:30:03+00:00"},"item":{"type":"array","items":{"$ref":"#/components/schemas/QuestionnaireResponseItem"},"description":"Groups and questions"},"extension":{"type":"array","items":{"required":["url"],"type":"object","properties":{"url":{"type":"string","description":"Identifies the meaning of the extension","format":"uri"},"valuePeriod":{"$ref":"#/components/schemas/QRPeriod"},"valueString":{"type":"string"},"valueBoolean":{"type":"boolean"},"valueInteger":{"type":"integer"},"valueDateTime":{"type":"string","format":"date-time"}}},"description":"Additional content defined by implementations"}},"description":"A FHIR QuestionnaireResponse resource representing a completed or in-progress questionnaire."},"QRIdentifier":{"required":["system","value"],"type":"object","properties":{"system":{"type":"string","description":"The namespace for the identifier value","format":"uri","example":"https://fhir.nhs.uk/Id/nhs-number"},"value":{"type":"string","description":"The value that is unique within the system","example":"9000000001"}},"description":"An identifier - identifies some entity uniquely and unambiguously"},"QRPeriod":{"type":"object","properties":{"start":{"type":"string","description":"Starting time with inclusive boundary","format":"date","example":"2026-05-05"},"end":{"type":"string","description":"End time with inclusive boundary","format":"date","example":"2027-05-05"}},"description":"Time period defined by a start and end date/time"},"QuestionnaireResponseItem":{"required":["linkId"],"type":"object","properties":{"linkId":{"type":"string","description":"Pointer to specific item from Questionnaire","example":"question_1_group"},"text":{"type":"string","description":"Name for group or question text","example":"Why are you making this follow-up request?"},"answer":{"type":"array","items":{"$ref":"#/components/schemas/QuestionnaireResponseItemAnswer"},"description":"The response(s) to the question"},"item":{"type":"array","items":{"$ref":"#/components/schemas/QuestionnaireResponseItem"},"description":"Nested questionnaire response items (for groups)"}},"description":"Groups and questions in the questionnaire response"},"QuestionnaireResponseItemAnswer":{"type":"object","properties":{"valueBoolean":{"type":"boolean","description":"Answer value when answer is a boolean"},"valueDecimal":{"type":"number","description":"Answer value when answer is a decimal","format":"double"},"valueInteger":{"type":"integer","description":"Answer value when answer is an integer"},"valueDate":{"type":"string","description":"Answer value when answer is a date","format":"date"},"valueDateTime":{"type":"string","description":"Answer value when answer is a date-time","format":"date-time"},"valueTime":{"pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)(\\.[0-9]+)?$","type":"string","description":"Answer value when answer is a time"},"valueString":{"type":"string","description":"Answer value when answer is a string","example":""},"valueUri":{"type":"string","description":"Answer value when answer is a URI","format":"uri"},"valueAttachment":{"type":"object","properties":{"contentType":{"type":"string"},"data":{"type":"string","format":"byte"},"url":{"type":"string","format":"uri"}},"description":"Answer value when answer is an attachment"},"valueCoding":{"$ref":"#/components/schemas/QRCoding"},"valueQuantity":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":"string"},"system":{"type":"string","format":"uri"},"code":{"type":"string"}},"description":"Answer value when answer is a quantity"},"valueReference":{"type":"object","properties":{"reference":{"type":"string"},"type":{"type":"string"},"identifier":{"$ref":"#/components/schemas/QRIdentifier"}},"description":"Answer value when answer is a reference"},"item":{"type":"array","items":{"$ref":"#/components/schemas/QuestionnaireResponseItem"},"description":"Nested groups and questions"}},"description":"The response(s) to the question"},"QRCoding":{"type":"object","properties":{"system":{"type":"string","description":"Identity of the terminology system","format":"uri","example":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason"},"code":{"type":"string","description":"Symbol in syntax defined by the system","example":"SYMPTOMS_GETTING_WORSE"},"display":{"type":"string","description":"Representation defined by the system","example":"My symptoms are getting worse"},"version":{"type":"string","description":"Version of the system - if relevant"}},"description":"A reference to a code defined by a terminology system"},"Bundle":{"required":["resourceType","type"],"type":"object","properties":{"resourceType":{"enum":["Bundle"],"type":"string","description":"FHIR resource type."},"id":{"type":"string","description":"The X-Correlation-ID from the Request header","example":{"$ref":"#/components/parameters/xCorrelationId/schema/example"}},"meta":{"type":"object","properties":{"versionId":{"pattern":"^[A-Za-z0-9\\-\\.]{1,64}$","type":"string","description":"FHIR id string representing the version of the resource","example":"1.0.0"},"profile":{"type":"array","items":{"enum":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreBundle"],"type":"string","description":"Wayfinder UK Core `Bundle` `StructureDefinition`"},"description":"Profiles this resource claims to conform to"}},"description":"Metadata about the resource"},"type":{"enum":["searchset"],"type":"string","description":"The type of FHIR bundle."},"total":{"type":"number","description":"The total number of matches","example":1},"entry":{"minItems":0,"type":"array","items":{"anyOf":[{"required":["fullUrl","resource","search"],"type":"object","properties":{"fullUrl":{"type":"string","description":"URI for the `QuestionnaireResponse` resource.","example":"https://api.service.nhs.uk/questionnaires/FHIR/R4/QuestionnaireResponse/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c"},"search":{"required":["mode"],"type":"object","properties":{"mode":{"enum":["match"],"type":"string","description":"Indicates why this resource is in the result set."}},"description":"Search-related information for the `QuestionnaireResponse` resource."},"resource":{"$ref":"#/components/schemas/QuestionnaireResponse"}},"description":"A questionnaire response entry."},{"required":["fullUrl","resource","search"],"type":"object","properties":{"fullUrl":{"type":"string","description":"URI for the `OperationOutcome` resource.","example":"https://api.service.nhs.uk/questionnaires/FHIR/R4/OperationOutcome/c93e2449-a2ef-4476-ad15-13491036be22"},"search":{"required":["mode"],"type":"object","properties":{"mode":{"enum":["include"],"type":"string","description":"Indicates why this resource is in the result set."}},"description":"Search-related information for the `OperationOutcome` resource."},"resource":{"$ref":"#/components/schemas/OperationOutcome"}},"description":"Details of any errors, expressed as a FHIR `OperationOutcome` resource."}]},"description":"The FHIR resources within the bundle.\nIncludes `0..*` `QuestionnaireResponse` resources and `0..1` `OperationOutcome` resources (if errors occurred).\n"}},"description":"A FHIR `Bundle` resource containing the search results of the request.","externalDocs":{"description":"FHIR UK Core Bundle (R4) Resource Profile","url":"https://hl7.org/fhir/R4/bundle.html"}},"OperationOutcome":{"required":["resourceType","issue"],"type":"object","properties":{"resourceType":{"minLength":1,"enum":["OperationOutcome"],"type":"string","description":"FHIR resource type."},"id":{"type":"string","description":"The X-Correlation-ID from the Request header","example":{"$ref":"#/components/parameters/xCorrelationId/schema/example"}},"issue":{"minItems":1,"uniqueItems":true,"type":"array","items":{"required":["severity","code"],"type":"object","properties":{"severity":{"minLength":1,"enum":["error"],"type":"string","description":"Severity of the issue."},"code":{"minLength":1,"enum":["required","invalid","security","forbidden","not-found","exception"],"type":"string","description":"Error code for the issue. See [http://hl7.org/fhir/issue-type](http://hl7.org/fhir/issue-type).\n"},"diagnostics":{"minLength":1,"type":"string","description":"Detailed diagnostic information for the issue.","example":"Response failed FHIR validation"}},"description":"An issue that occurred."},"description":"An array of issues that occurred in processing the request. Usually there is only one issue, but there can be more than one."}},"description":"A FHIR `OperationOutcome` resource containing details of the issues that have occurred."}},"responses":{"SuccessQuestionnaire":{"description":"Successful retrieval of questionnaire resources.","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/Bundle"},"examples":{"emptyBundle":{"$ref":"#/components/examples/emptyBundle"},"sampleQuestionnaireBundle":{"$ref":"#/components/examples/sampleQuestionnaireBundle"}}}}},"BadRequestQuestionnaire":{"description":"Bad Request - The request is invalid. This can occur due to:\n- Missing X-Correlation-ID header\n- Missing required query parameters (_tag, context)\n- Invalid treatment function code format in _tag\n- Invalid ODS code format in context\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"missingCorrelationId":{"$ref":"#/components/examples/missingCorrelationId"},"missingTag":{"$ref":"#/components/examples/missingTag"},"missingContext":{"$ref":"#/components/examples/missingContext"},"invalidTagFormat":{"$ref":"#/components/examples/invalidTagFormat"},"invalidContextFormat":{"$ref":"#/components/examples/invalidContextFormat"}}}}},"Success":{"description":"The request was valid and the API was able to request information from the various upstream applications.\n\nA successful request will return a HTTP status code of `200 OK` containing a FHIR `Bundle` with `0..*` `QuestionnaireResponse` resources.\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/Bundle"},"examples":{"emptyBundle":{"$ref":"#/components/examples/emptyBundle"},"sampleQuestionnaireResponse":{"$ref":"#/components/examples/sampleQuestionnaireResponse"}}}}},"BadRequest":{"description":"Bad Request - The request is invalid. This can occur due to:\n- Missing X-Correlation-ID header\n- Missing required query parameters (subject:identifier, source:identifier, _tag)\n- Invalid NHS number format in subject:identifier\n- Invalid ODS code format in source:identifier\n\nA FHIR `OperationOutcome` resource is returned. For details see the `diagnostics` field.\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"missingCorrelationId":{"$ref":"#/components/examples/missingCorrelationId"},"missingSubjectIdentifier":{"$ref":"#/components/examples/missingSubjectIdentifier"},"missingSourceIdentifier":{"$ref":"#/components/examples/missingSourceIdentifier"},"missingTag":{"$ref":"#/components/examples/missingTag"},"invalidNhsNumberFormat":{"$ref":"#/components/examples/invalidNhsNumberFormat"},"invalidOdsCodeFormat":{"$ref":"#/components/examples/invalidOdsCodeFormat"}}}}},"Unauthorized":{"description":"Unauthorized - Authentication failure. This can occur due to:\n- Missing NHSD ID token\n- APIM authentication failed when exchanging the NHSD ID token\n- Missing or invalid OAuth 2.0 bearer token (from APIM)\n\nThis response is generated by API Gateway/APIM authentication layers and is not guaranteed\nto be a FHIR `OperationOutcome`.\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/json":{"examples":{"missingNhsdIdToken":{"$ref":"#/components/examples/missingNhsdIdToken"},"authenticationFailed":{"$ref":"#/components/examples/authenticationFailed"},"invalidAuthToken":{"$ref":"#/components/examples/invalidAuthToken"}}}}},"Forbidden":{"description":"Forbidden - Patient is under 16 years of age.\n\nThis response is generated by API Gateway when the Lambda authorizer denies access,\nso response body shape is gateway-managed and not guaranteed to be FHIR.\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/json":{"examples":{"under16":{"$ref":"#/components/examples/under16"}}}}},"NotFound":{"description":"Not Found - The requested resource or operation was not found.\n\nA FHIR `OperationOutcome` resource is returned. For details see the `diagnostics` field.\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"unsupportedOperation":{"$ref":"#/components/examples/unsupportedOperation"}}}}},"TooManyRequests":{"description":"Too Many Requests - You have exceeded your application's [rate limit](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#rate-limits).\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/json":{"examples":{"rateLimit":{"$ref":"#/components/examples/rateLimit"}}}}},"InternalServerError":{"description":"Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request. This can occur due to:\n- Unexpected errors during request processing\n- Errors communicating with the PDM system\n- Uncaught exceptions\n\nFor more details on 5xx status codes see the [HTTP status codes](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes).\n","headers":{"X-Correlation-ID":{"name":"","in":"header","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"$ref":"#/components/headers/xCorrelationId"}},"content":{"application/fhir+json":{"schema":{"$ref":"#/components/schemas/OperationOutcome"},"examples":{"internalError":{"$ref":"#/components/examples/internalError"},"pdmProcessingError":{"$ref":"#/components/examples/pdmProcessingError"}}}}}},"parameters":{"Authorization":{"name":"Authorization","in":"header","description":"An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).\n\nRequired in all environments except sandbox.\n\nIn the sandbox environment, this header is ignored.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^Bearer\\ [[:ascii:]]+$","type":"string","example":"Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM"}},"xCorrelationId":{"name":"X-Correlation-ID","in":"header","description":"An identifier which is used to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"uuid","example":"c93e2449-a2ef-4476-ad15-13491036be22"}},"nhsNumber":{"name":"patient:identifier","in":"query","description":"The patient's NHS number.\nExpressed as `<type>|<value>` where `<type>` must be `https://fhir.nhs.uk/Id/nhs-number` and `<value>` must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^https:\\/\\/fhir\\.nhs\\.uk\\/Id\\/nhs-number\\|[1-9][0-9]{9}$","type":"string","example":"https://fhir.nhs.uk/Id/nhs-number|9000000009"}},"subjectIdentifier":{"name":"subject:identifier","in":"query","description":"The patient's NHS number.\nExpressed as `<type>|<value>` where `<type>` must be `https://fhir.nhs.uk/Id/nhs-number` and `<value>` must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^https:\\/\\/fhir\\.nhs\\.uk\\/Id\\/nhs-number\\|[1-9]\\d{9}$","type":"string","example":"https://fhir.nhs.uk/Id/nhs-number|9000000009"}},"sourceIdentifier":{"name":"source:identifier","in":"query","description":"The healthcare organization's ODS code.\nExpressed as `<type>|<value>` where `<type>` must be `https://fhir.nhs.uk/Id/ods-organization-code` and `<value>` must be a valid ODS organization code.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^https:\\/\\/fhir\\.nhs\\.uk\\/Id\\/ods-organization-code\\|[A-Z0-9]+$","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code|RTK"}},"tag":{"name":"_tag","in":"query","description":"A tag to filter questionnaire responses by treatment function code.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-treatment-function|301"}},"context":{"name":"context","in":"query","description":"ODS organisation filter as `system|code`.","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"pattern":"^https:\\/\\/fhir\\.nhs\\.uk\\/Id\\/ods-organization-code\\|[A-Z][A-Z0-9]{2,7}$","type":"string","example":"https://fhir.nhs.uk/Id/ods-organization-code|RX8"}},"elements":{"name":"_elements","in":"query","description":"Optional parameter to request only specific elements of the QuestionnaireResponse resources.\n","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","example":"id,status,authored"}},"nhsdIdToken":{"name":"NHSD-ID-Token","in":"header","description":"Valid NHS login ID Token JWT issued from the corresponding environment, see Security and authorisation above.\n\nIn the sandbox environment, this header is ignored.\n","required":true,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"byte","example":"eyJzdWIiOiI4MmEyOTZkMC03NTJjLTRjZjEtOWEwMC03MzgwNmJiMWY4MzMiLCJhdWQiOiJuaHMtb25saW5lIiwia2lkIjoiZjYwZWI0NmZmOGFiZjBiZjllOTE3ZWVlNjA4NmM1ZmE0YTE2MmE1ZCIsImlzcyI6Imh0dHBzOi8vYXV0aC5hb3Muc2lnbmluLm5ocy51ayIsInR5cCI6IkpXVCIsImV4cCI6MTY1NzEwMTY4OCwiaWF0IjoxNjU3MDk4MDg4LCJhbGciOiJSUzUxMiIsImp0aSI6ImZjMzYyZGY0LWRlOWMtNDY1OS1hM2RmLWVmMDEwMDAwZjQ0MCJ9.eyJzdWIiOiI4MmEyOTZkMC03NTJjLTRjZjEtOWEwMC03MzgwNmJiMWY4MzMiLCJiaXJ0aGRhdGUiOiIxOTg1LTA5LTA3IiwibmhzX251bWJlciI6Ijk3MjY3NzkwNTciLCJpc3MiOiJodHRwczovL2F1dGguYW9zLnNpZ25pbi5uaHMudWsiLCJ2dG0iOiJodHRwczovL2F1dGguYW9zLnNpZ25pbi5uaHMudWsvdHJ1c3RtYXJrL2F1dGguYW9zLnNpZ25pbi5uaHMudWsiLCJhdWQiOiJuaHMtb25saW5lIiwiaWRfc3RhdHVzIjoidmVyaWZpZWQiLCJ0b2tlbl91c2UiOiJpZCIsInN1cm5hbWUiOiJDSE9OIiwiYXV0aF90aW1lIjoxNjU3MDk4MDgxLCJ2b3QiOiJQOS5DcC5DZCIsImlkZW50aXR5X3Byb29maW5nX2xldmVsIjoiUDkiLCJleHAiOjE2NTcxMDE2ODgsImlhdCI6MTY1NzA5ODA4OCwiZmFtaWx5X25hbWUiOiJDSE9OIiwianRpIjoiZmMzNjJkZjQtZGU5Yy00NjU5LWEzZGYtZWYwMTAwMDBmNDQwIn0.fEar_s6EaRWj1oWW1Kb_ekYFH2zPOjH4GdixoXKxvc7H7BEAnBt3k9FUMVIg9UD5i-4iu7hUy5p_0BbFZL5mPFFAnW67lAZV2D8FOcHDNunDU64ov5nNsBubHGOotRpExgHBxCF31eHonzzE8g2A7j4mmZJxlJ0MX-qCuF3CRiAc1apI_2ugPEDTFkX53YBNtDg2kDUVDTthCDdg1ylOiHunCurCXMaJSPmOGsac_ltRgYM_fs64MXoLmSNXUvxWa18N4689vipQ9hG4VASQQvPYMkgiynv6oX8ME9RPbBdmlTceeuEXiwLrvXtrU4xZkU3Js1x9DNTkZ96Fg9-yOQ"}}},"examples":{"emptyBundle":{"summary":"200 Empty bundle / no activity","description":"A response where all upstream systems responded normally (HTTP status 200). Contains no resources.\n```\nBundle\n```\n","value":{"resourceType":"Bundle","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"versionId":"3.3.4","profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreBundle"]},"type":"searchset","total":0,"entry":[]}},"sampleQuestionnaireResponse":{"summary":"200 Sample QuestionnaireResponse in Bundle","description":"A complete example of a Bundle containing QuestionnaireResponse resources showing the structure and data format.\n```\nBundle\n├── QuestionnaireResponse (completed)\n```\n","value":{"resourceType":"Bundle","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"versionId":"3.3.4","profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreBundle"]},"type":"searchset","total":2,"entry":[{"fullUrl":"https://api.service.nhs.uk/questionnaires/FHIR/R4/QuestionnaireResponse/c21417eb-ffef-4a9e-b367-ebd8b8c29e7c","search":{"mode":"match"},"resource":{"resourceType":"QuestionnaireResponse","basedOn":[{"type":"CarePlan","identifier":{"system":"https://fhir.nhs.uk/Id/PathwayId","value":"RAB~RBH5644312231"}}],"questionnaire":"https://api.service.nhs.uk/questionnaires/FHIR/R4/Questionnaire/36321f2e-103c-41a8-9f4d-90d39cd925d3","status":"completed","subject":{"type":"Patient","identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000001"}},"source":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"A6U7U"}},"meta":{"tag":[{"system":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-treatment-function","code":"100"},{"system":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-clinical-specialty","code":"110"}]},"authored":"2025-01-16T15:30:03Z","item":[{"linkId":"question_1_group","item":[{"linkId":"question_1_supporting_text","text":"You can only request follow-ups for conditions or symptoms related to your patient-initiated follow-up.\nFollow the advice included in the letter from your hospital or specialist care provider. Contact your healthcare team if you do not have this information."},{"linkId":"question_1","text":"Why are you making this follow-up request?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"SYMPTOMS_GETTING_WORSE","display":"My symptoms are getting worse"}}]}]},{"linkId":"question_2_group","item":[{"linkId":"question_2","text":"How long have you been experiencing this?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"TWO_TO_FOUR_WEEKS","display":"2-4 weeks"}}]}]},{"linkId":"question_3_group","item":[{"linkId":"question_3","text":"How much impact is this having on your daily life?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"MODERATE_IMPACT","display":"Moderate impact"}}]}]}],"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/artifact-effectivePeriod","valuePeriod":{"start":"2026-05-05","end":"2027-05-05"}}]}},{"fullUrl":"https://api.service.nhs.uk/questionnaires/FHIR/R4/QuestionnaireResponse/f8392d1c-8945-4e2f-b8c3-d5e6a9c7f234","search":{"mode":"match"},"resource":{"resourceType":"QuestionnaireResponse","basedOn":[{"type":"CarePlan","identifier":{"system":"https://fhir.nhs.uk/Id/PathwayId","value":"RAB~RBH5644312232"}}],"questionnaire":"https://api.service.nhs.uk/questionnaires/FHIR/R4/Questionnaire/a7b8c9d0-1234-5678-90ab-cdef12345678","status":"in-progress","subject":{"type":"Patient","identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000001"}},"source":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"A6U7U"}},"meta":{"tag":[{"system":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-treatment-function","code":"320"}]},"authored":"2025-12-20T10:15:00Z","item":[{"linkId":"question_1_group","item":[{"linkId":"question_1_supporting_text","text":"You can only request follow-ups for conditions or symptoms related to your patient-initiated follow-up.\nFollow the advice included in the letter from your hospital or specialist care provider. Contact your healthcare team if you do not have this information."},{"linkId":"question_1","text":"Why are you making this follow-up request?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"HAVE_A_QUESTION","display":"I have a question"}}]}]},{"linkId":"question_2_group","item":[{"linkId":"question_2","text":"How long have you been experiencing this?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"ONE_TO_TWO_WEEKS","display":"1-2 weeks"}}]}]},{"linkId":"question_3_group","item":[{"linkId":"question_3","text":"How much impact is this having on your daily life?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"SOME_IMPACT","display":"Some impact"}}]}]}],"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/artifact-effectivePeriod","valuePeriod":{"start":"2025-12-01","end":"2026-12-01"}}]}}]}},"questionnaireResponseCreateRequest":{"summary":"POST QuestionnaireResponse request body","description":"A sample request payload for creating a QuestionnaireResponse.","value":{"resourceType":"QuestionnaireResponse","basedOn":[{"type":"CarePlan","identifier":{"system":"https://fhir.nhs.uk/Id/PathwayId","value":"RAB~RBH5644312231"}}],"questionnaire":"https://api.service.nhs.uk/questionnaires/FHIR/R4/Questionnaire/36321f2e-103c-41a8-9f4d-90d39cd925d3","status":"completed","subject":{"type":"Patient","identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000001"}},"source":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"A6U7U"}},"meta":{"tag":[{"system":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-treatment-function","code":"100"}]},"authored":"2025-01-16T15:30:03Z","item":[{"linkId":"question_1_group","item":[{"linkId":"question_1","text":"Why are you making this follow-up request?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"SYMPTOMS_GETTING_WORSE","display":"My symptoms are getting worse"}}]},{"linkId":"question_1_supporting_text","text":"You can only request follow-ups for conditions or symptoms related to your patient-initiated follow-up.\nFollow the advice included in the letter from your hospital or specialist care provider. Contact your healthcare team if you do not have this information."}]},{"linkId":"question_2_group","item":[{"linkId":"question_2","text":"How long have you been experiencing this?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"TWO_TO_FOUR_WEEKS","display":"2-4 weeks"}}]}]},{"linkId":"question_3_group","item":[{"linkId":"question_3","text":"How much impact is this having on your daily life?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"MODERATE_IMPACT","display":"Moderate impact"}}]}]}],"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/artifact-effectivePeriod","valuePeriod":{"start":"2026-05-05","end":"2027-05-05"}}]}},"questionnaireResponseAcceptedResponse":{"summary":"202 QuestionnaireResponse accepted","description":"A sample accepted response containing the created QuestionnaireResponse id.","value":{"id":"c21417eb-ffef-4a9e-b367-ebd8b8c29e7c","resourceType":"QuestionnaireResponse","basedOn":[{"type":"CarePlan","identifier":{"system":"https://fhir.nhs.uk/Id/PathwayId","value":"RAB~RBH5644312231"}}],"questionnaire":"https://api.service.nhs.uk/questionnaires/FHIR/R4/Questionnaire/36321f2e-103c-41a8-9f4d-90d39cd925d3","status":"completed","subject":{"type":"Patient","identifier":{"system":"https://fhir.nhs.uk/Id/nhs-number","value":"9000000001"}},"source":{"identifier":{"system":"https://fhir.nhs.uk/Id/ods-organization-code","value":"A6U7U"}},"meta":{"tag":[{"system":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-treatment-function","code":"100"}]},"authored":"2025-01-16T15:30:03Z","item":[{"linkId":"question_1_group","item":[{"linkId":"question_1_supporting_text","text":"You can only request follow-ups for conditions or symptoms related to your patient-initiated follow-up.\nFollow the advice included in the letter from your hospital or specialist care provider. Contact your healthcare team if you do not have this information."},{"linkId":"question_1","text":"Why are you making this follow-up request?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"SYMPTOMS_GETTING_WORSE","display":"My symptoms are getting worse"}}]}]},{"linkId":"question_2_group","item":[{"linkId":"question_2","text":"How long have you been experiencing this?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"TWO_TO_FOUR_WEEKS","display":"2-4 weeks"}}]}]},{"linkId":"question_3_group","item":[{"linkId":"question_3","text":"How much impact is this having on your daily life?","answer":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"MODERATE_IMPACT","display":"Moderate impact"}}]}]}],"extension":[{"url":"http://hl7.org/fhir/StructureDefinition/artifact-effectivePeriod","valuePeriod":{"start":"2026-05-05","end":"2027-05-05"}}]}},"sampleQuestionnaireBundle":{"summary":"200 Bundle with Questionnaire","value":{"resourceType":"Bundle","id":"c93e2449-a2ef-4476-ad15-13491036be22","type":"searchset","total":1,"entry":[{"resource":{"resourceType":"Questionnaire","id":"44cad113-50ba-4b7e-9d46-c067876417c5","title":"National PIFU Question - 301 RTK","version":"1.0","status":"active","date":"2025-01-10","publisher":"NHS England","meta":{"profile":["https://fhir.hl7.org.uk/StructureDefinition/UKCore-Questionnaire"],"tag":[{"system":"https://fhir.nhs.uk/CodeSystem/NHSDataModelAndDictionary-treatment-function","code":301}]},"useContext":[{"code":{"system":"http://terminology.hl7.org/CodeSystem/usage-context-type","code":"jurisdiction"},"valueCodeableConcept":{"coding":[{"system":"https://fhir.nhs.uk/Id/ods-organization-code","code":"RTK"}]}}],"item":[{"linkId":"question_1_group","text":"Why are you making this follow-up request?","type":"group","item":[{"linkId":"question_1_supporting_text","text":"You can only request follow-ups for conditions or symptoms related to your patient-initiated follow-up.\n\nFollow the advice included in the letter from your hospital or specialist care provider. Contact your healthcare team if you do not have this information.\n","type":"display"},{"linkId":"question_1","text":"Why are you making this follow-up request?","type":"coding","repeats":false,"required":true,"answerOption":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"SYMPTOMS_GETTING_WORSE","display":"My symptoms are getting worse"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"CONDITION_NOT_IMPROVING","display":"My condition is not improving"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"NEW_SYMPTOM","display":"I have a new symptom"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesFollowUpReason","code":"HAVE_A_QUESTION","display":"I have a question"}}]}]},{"linkId":"question_2_group","text":"How long have you been experiencing this?","type":"group","item":[{"linkId":"question_2","text":"How long have you been experiencing this?","type":"coding","repeats":false,"required":true,"answerOption":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"LESS_THAN_1_WEEK","display":"Less than 1 week"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"ONE_TO_TWO_WEEKS","display":"1-2 weeks"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"TWO_TO_FOUR_WEEKS","display":"2-4 weeks"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"MORE_THAN_4_WEEKS","display":"More than 4 weeks"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesSymptomDuration","code":"NOT_APPLICABLE","display":"Not applicable"}}]}]},{"linkId":"question_3_group","text":"How much impact is this having on your daily life?","type":"group","item":[{"linkId":"question_3","text":"How much impact is this having on your daily life?","type":"coding","repeats":false,"required":true,"answerOption":[{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"NO_IMPACT","display":"No impact"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"SOME_IMPACT","display":"Some impact"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"MODERATE_IMPACT","display":"Moderate impact"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"SEVERE_IMPACT","display":"Severe impact"}},{"valueCoding":{"system":"https://fhir.nhs.uk/England/CodeSystem/England-QuestionnairesDailyLifeImpact","code":"NOT_APPLICABLE","display":"Not applicable"}}]}]}]}}]}},"missingContext":{"summary":"400 Missing context query parameter","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","issue":[{"severity":"error","code":"invalid","diagnostics":"'context' is a required property"}]}},"invalidTagFormat":{"summary":"400 Invalid _tag format","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","issue":[{"severity":"error","code":"invalid","diagnostics":"'_tag' does not match required pattern"}]}},"invalidContextFormat":{"summary":"400 Invalid context format","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","issue":[{"severity":"error","code":"invalid","diagnostics":"'context' does not match required pattern"}]}},"missingCorrelationId":{"summary":"400 Missing X-Correlation-ID header","description":"The required X-Correlation-ID header is missing from the request.","value":{"resourceType":"OperationOutcome","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"required","diagnostics":"Missing X-Correlation-ID header"}]}},"missingSubjectIdentifier":{"summary":"400 Missing subject:identifier query parameter","description":"The required subject:identifier query parameter is missing.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"invalid","diagnostics":"'subject:identifier' is a required property"}]}},"missingSourceIdentifier":{"summary":"400 Missing source:identifier query parameter","description":"The required source:identifier query parameter is missing.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"invalid","diagnostics":"'source:identifier' is a required property"}]}},"missingTag":{"summary":"400 Missing _tag query parameter","description":"The required _tag query parameter is missing.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"invalid","diagnostics":"'_tag' is a required property"}]}},"invalidNhsNumberFormat":{"summary":"400 Invalid NHS number format in subject:identifier","description":"The subject:identifier query parameter does not match the required pattern.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"invalid","diagnostics":"'subject:identifier' with value 'https://fhir.nhs.uk/Id/nhs-number|123' does not match '^https://fhir\\.nhs\\.uk/Id/nhs-number\\|[1-9]\\d{9}$'"}]}},"invalidOdsCodeFormat":{"summary":"400 Invalid ODS code format in source:identifier","description":"The source:identifier query parameter does not match the required pattern.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"invalid","diagnostics":"'source:identifier' with value 'https://fhir.nhs.uk/Id/ods-organization-code|abc' does not match '^https://fhir\\.nhs\\.uk/Id/ods-organization-code\\|[A-Z0-9]+$'"}]}},"missingNhsdIdToken":{"summary":"401 Missing NHSD ID token","description":"The required NHSD ID token is missing from the request.","value":{"message":"Unauthorized"}},"authenticationFailed":{"summary":"401 Authentication failed","description":"APIM authentication failed when exchanging the NHSD ID token.","value":{"message":"Unauthorized"}},"invalidAuthToken":{"summary":"401 Missing or invalid OAuth 2.0 bearer token in request","description":"We do not explicitly serve this request but you may expect to receive this from APIM following a failed authentication process.","value":{"message":"Unauthorized"}},"under16":{"summary":"403 Patient is under 16 years of age","description":"The NHS Login token containing the patients birthdate is compared to the system date/time. When the patient is under 16 years old the following error is returned","value":{"message":"Forbidden"}},"unsupportedOperation":{"summary":"404 Unsupported operation","description":"The requested operation or endpoint is not supported.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"not-found","diagnostics":"Unsupported operation"}]}},"rateLimit":{"summary":"429 You have exceeded your application's rate limit.","description":"We do not explicitly serve this request but you may expect to receive this from APIM following rate limiting. This is not a FHIR response.","value":{"message":"Your application, Wayfinder - Questionnaire Responses Service - INT, has exceeded its quota of 6000 requests every 1 minute(s) and is being rate limited.","scope":"application","policy":"quota","limit":6000,"interval":1,"timeunit":"minute","ratelimiting_expiry_time_ms":1716896160000,"message_id":"rrt-4746096881325101106-b-geu2-22287-470757-1"}},"internalError":{"summary":"500 Internal Server Error","description":"For uncaught internal errors or unexpected exceptions.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"exception","diagnostics":"Internal Server Error"}]}},"pdmProcessingError":{"summary":"500 Error processing request","description":"An error occurred while executing the operation against the PDM system.","value":{"resourceType":"OperationOutcome","id":"c93e2449-a2ef-4476-ad15-13491036be22","meta":{"profile":["https://fhir.nhs.uk/StructureDefinition/WayfinderUKCoreOperationOutcome"]},"issue":[{"severity":"error","code":"exception","diagnostics":"Error processing request"}]}}},"headers":{"xCorrelationId":{"name":"","in":"header","description":"Request parameter value echoed back (when provided). For gateway-generated authentication deny responses, this header may be absent.","required":false,"deprecated":false,"allowEmptyValue":false,"explode":false,"allowReserved":false,"schema":{"type":"string","format":"uuid","example":"c93e2449-a2ef-4476-ad15-13491036be22"}}},"securitySchemes":{"nhs-login-p9":{"$ref":"https://proxygen.ptl.api.platform.nhs.uk/components/securitySchemes/nhs-login-p9"}}},"security":[{"nhs-login-p9":[]}],"tags":[{"name":"Questionnaires","description":"Wayfinder - Questionnaires","externalDocs":{"url":"https://digital.nhs.uk/developer/api-catalogue/patient-care-aggregator-fhir"}},{"name":"Questionnaire Responses","description":"Wayfinder - Questionnaire Responses","externalDocs":{"url":"https://digital.nhs.uk/developer/api-catalogue/patient-care-aggregator-fhir"}},{"name":"Authentication","description":"Authentication for user session details.","externalDocs":{"url":"https://digital.nhs.uk/developer/api-catalogue/patient-care-aggregator-fhir"}}]}