openapi: 3.0.0
info:
  version: 0.3.4-beta
  title: Reasonable Adjustment Flag API
  description: |-
    <div class="nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6" aria-label="Highlighted Information">
        <div class="nhsd-a-box nhsd-a-box--border-blue">
            <div class="nhsd-m-emphasis-box__image-box">
                <figure class="nhsd-a-image">
                    <picture class="nhsd-a-image__picture">
                        <img src="http://digital.nhs.uk/binaries/content/gallery/icons/info.svg?colour=231f20" alt="" style="object-fit:fill">
                    </picture>
                </figure>
            </div>
            <div class="nhsd-m-emphasis-box__content-box">
                <div data-uipath="website.contentblock.emphasis.content" class="nhsd-t-word-break"><p class="nhsd-t-body">This API is <a href="https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses">retired</a> and not available for use - use the <a href="https://digital.nhs.uk/developer/api-catalogue/patient-flags-service---fhir-api">Patient Flags Service - FHIR API</a> instead.</p></div>
            </div>
        </div>
    </div>
    
    ## Overview
    Use this API to access and update the [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag#top) - a national record which indicates that a patient requires reasonable adjustments and optionally includes details of impairments and adjustments to be considered.

    You can:
     - check if a Reasonable Adjustment Flag exists
     - read a Reasonable Adjustment Flag
     - create a Reasonable Adjustment Flag
     - update a Reasonable Adjustment Flag
     - remove a Reasonable Adjustment Flag
     
    The flag consists of three parts:
     - details of consent to share the Flag and how this was obtained. Consent may have been given by the patient or via a 'best interest decision' under the [Mental Capacity Act (2005)](https://www.nhs.uk/conditions/social-care-and-support-guide/making-decisions-for-someone-else/mental-capacity-act/). In some cases consent can also be obtained from a lasting power of attorney for health and welfare or a court appointed deputy.
     - details of impairments, which enable clinicians to understand the range of adjustments the patient may require. Note that the patient may decline to say what their impairments are.
     - details of reasonable adjustments to services which are needed by the patient when providing their care. 

    This API can only be used by relevant health and care staff providing direct care, authenticated with an NHS [smartcard](https://digital.nhs.uk/services/registration-authorities-and-smartcards) or equivalent.

    The existance of a flag is intended to be visible to all staff who have access to the patient record.  The contents of the Flag may only be visible to clinical staff - as determined by role-based access controls (RBAC). For more details see [Registration authorities and smartcards](https://digital.nhs.uk/services/registration-authorities-and-smartcards).

    To find out more about how the flag works, categories and types of adjustments and the recording of impairments see [How the Reasonable Adjustment Flag works](https://digital.nhs.uk/services/reasonable-adjustment-flag#how-the-reasonable-adjustment-flag-works).

    To watch a video of a Reasonable Adjustment Flag being created in [SCRa](https://digital.nhs.uk/services/summary-care-record-application) see [Creating a Reasonable Adjustment Flag on the NHS Spine](https://www.youtube.com/watch?v=dX-IwYXXEwE).
    
    A healthcare worker must be present and authenticated with an [NHS smartcard or a modern alternative](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/nhs-smartcards-for-developers) to use this API.

    ## Who can use this API
    This API can only be used where there is a legal basis to do so. Make sure you have a valid use case before you go too far with your development. You must do this before you can go live (see ‘Onboarding’ below).

    ## Related APIs
    To use this API, you will need the patient's NHS number, which can be retrieved by using the following API:

      - [Personal Demographics Service (FHIR) API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir) - use this API to search for patients and retrieve their details.  This API can also be used to update their details in some cases.

     When using this API, we also recommend that you consider using these related APIs:

      - [Female Genital Mutilation Information Sharing System (FGM-IS)](https://developer.nhs.uk/apis/fgm-v2.1/) - use this API to store and share FGM information of children under 18 with relevant NHS healthcare professionals across departments, organisations and geographical boundaries within England.

      - [Child Protection Information Sharing (CP-IS) - HL7 V3 API](https://digital.nhs.uk/services/child-protection-information-sharing-project/cp-is-domain-message-specification) - use this API to provide access to CP-IS, a sharing system which provides healthcare workers with access to recent unscheduled care attendance information for children under a local authority social care plan. 

      - [National Record Locator (NRL) (FHIR) API](https://developer.nhs.uk/apis/nrl/) - use this API to locate and share patient records held within local health and social care systems.

    ## API status and roadmap
     This API is [is retired](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) and not available for use.
     
     The API is currently available for sandbox testing, but not integration testing or for production use.
         
    To see our roadmap, or to suggest, comment or vote on features for this API, see our [interactive product backlog](https://nhs-digital-api-management.featureupvote.com/?order=popular&filter=all&tag=reasonable-adjustment-flag#controls).

    If you have any other queries, please [contact us](https://digital.nhs.uk/developer/help-and-support).

    ## Technology
    This API is [RESTful](/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).

    It also conforms to the [FHIR (STU3)](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir) global standard for health care data exchange. Specifically it conforms to [FHIR Release 3](https://www.hl7.org/fhir/STU3/).

    You don’t need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules. In particular:
    - array names are singular, for example `line` not `lines` for address lines
    - data items that are country-specific and thus not included in the FHIR global base resources are usually wrapped in an `extension` object

    ### Resources
    For information on the resources used within the Reasonable Adjustment Flag API see [Reasonable Adjustment Flag FHIR specification](https://dev-reasonable-adjust-beta.netlify.app/explore.html).


    ## Network Access
    This 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). To use this API with [NHS smartcards](https://digital.nhs.uk/services/registration-authorities-and-smartcards), the end user needs an HSCN connection, although internet-facing alternatives to smartcards are available.

    For more details see [Network access for APIs](https://digital.nhs.uk/developer/guides-and-documentation/network-access-for-apis).

    ## Security and authorisation
    This 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 and authenticated to use it.

    The end user must be:
    - a healthcare professional
    - strongly authenticated, using either an NHS [smartcard](https://digital.nhs.uk/services/registration-authorities-and-smartcards) or a [modern alternative](https://digital.nhs.uk/services/nhs-care-identity-service-2/ways-to-authenticate-with-nhs-cis2) available via [NHS Care Identity Service 2 (NHS CIS2)](https://digital.nhs.uk/services/nhs-care-identity-service-2)

    The API uses OAuth 2.0 to authorise the calling system. It supports the following security patterns:

    - [user-restricted RESTful API - using NHS CIS2 - combined authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-combined-authentication-and-authorisation)
    - [user-restricted RESTful API - using NHS CIS2 - separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation)

    For more details, see [user-restricted APIs](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).

    You must implement role-based access controls (RBAC) within your application to determine whether the end user is allowed to see (and update) the details of the record or only to know of its existence.

    For more details see [Registration authorities and smartcards](https://digital.nhs.uk/services/registration-authorities-and-smartcards).


    ## Environments and testing
    | Purpose                                | Base URL                                 |
    | ---------------------------------------|------------------------------------------|
    | Sandbox                                | `https://sandbox.service.nhs.uk/reasonable-adjustment-flag/FHIR/STU3`    |
    | Integration test **(available Jan 2021)**  | `https://int.service.nhs.uk/reasonable-adjustment-flag/FHIR/STU3`        |
    | Production **(available Mar 2021)** | `https://api.service.nhs.uk/reasonable-adjustment-flag/FHIR/STU3`      |


    ### Sandbox testing
    Our [sandbox environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#sandbox-testing):
      - is for early developer testing
      - only covers a limited set of scenarios
      - is stateless, so it does not actually persist any updates
      - is open access, so does not allow you to test authorisation 

    For more details on sandbox testing, or to try out the sandbox using our \"Try this API\" feature, see the documentation for each endpoint.

    ### Integration testing
    Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):
    * is for formal integration testing
    * is stateful, so persists updates
    * includes authorisation, with options for user-restricted access (with or without [smartcards](https://digital.nhs.uk/services/registration-authorities-and-smartcards))

    To test updating patient details, you must set up your own test data.

    For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).

    ## Onboarding
    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.
    
    As part of this process, you need to demonstrate that you can manage risks and that your software conforms technically with the requirements for this API.
    
    Information on this page might impact the design of your software. For details, see [Onboarding support information](https://digital.nhs.uk/developer/api-catalogue/reasonable-adjustment-flag-fhir/onboarding-support-information).
    
    To understand how our online digital onboarding process works, see [digital onboarding](https://digital.nhs.uk/developer/guides-and-documentation/digital-onboarding).
    
    <div class="nhsd-m-emphasis-box nhsd-m-emphasis-box--emphasis nhsd-!t-margin-bottom-6" aria-label="Highlighted Information">
        <div class="nhsd-a-box nhsd-a-box--border-blue">
            <div class="nhsd-m-emphasis-box__image-box">
                <figure class="nhsd-a-image">
                    <picture class="nhsd-a-image__picture">
                        <img src="http://digital.nhs.uk/binaries/content/gallery/icons/play-circle.svg?colour=231f20" alt="" style="object-fit:fill">
                    </picture>
                </figure>
            </div>
            <div class="nhsd-m-emphasis-box__content-box">
                <div data-uipath="website.contentblock.emphasis.content" class="nhsd-t-word-break"><p class="nhsd-t-body">To get started, sign in or create a <a href="https://onboarding.prod.api.platform.nhs.uk/">developer account</a>, then select 'product onboarding'.</p></div>            
            </div>
        </div>
    </div> 
    
    ## Errors
    We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

    * 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
    * 400 to 499 if it failed because of a client error by your application
    * 500 to 599 if it failed because of an error on our server
    
    Errors 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.
    
    ## Using this API
    To check if a Reasonable Adjustment Flag exists:
     - get consent details - if they exist, the overall record exists

    To get a Reasonable Adjustment Flag:
     - get consent details
     - get reasonable adjustment details - which might not exist
     - get impairments - which might not exist

    To create a Reasonable Adjustment Flag:
     - add consent details - doing this also creates the overall record
     - optionally, add reasonable adjustments
     - optionally, add impairments

    To update a Reasonable Adjustment Flag:
     - get the relevant part(s) of the record first - you’ll need the version number for the update
     - update consent details, reasonable adjustments or impairments as appropriate

    To remove a Reasonable Adjustment Flag:
     - remove Reasonable Adjustment Flag record - this single operation will remove the record in its entirety
  contact:
    name: API Management Support
    email: api.management@nhs.net
servers:
  - url: 'https://sandbox.api.service.nhs.uk/reasonable-adjustment-flag/FHIR/STU3'
    description: Sandbox environment.
paths:
  /Consent:
    post:
      summary: Create Flag and add consent details
      description: |-
        ## Overview
        Use this endpoint to create a Reasonable Adjustment Flag for a patient and add details regarding the patient's consent to share it, as well as how this was obtained.

        For full details of the request payload for this endpoint, see [RARecord-Consent-1](https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Consent-1).
      operationId: postConsent
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      requestBody:
        description: Create consent
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: components/schemas/createConsent.yaml
            example:
              $ref: components/examples/createConsent.json
      responses:
        '201':
          description: Reasonable Adjustment Flag created and consent details added.
          headers:
            ETag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Location:
              $ref: components/schemas/Location.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                  $ref: components/examples/createConsentResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it.|\t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

    get:
      summary: Get consent details
      description: |-
        ## Overview
        Use this endpoint to read details regarding the patient's consent to share a [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) record, as well as how this was obtained. Consent may have been given by the patient or via a 'best interest decision' under the [Mental Capacity Act (2005)](https://www.nhs.uk/conditions/social-care-and-support-guide/making-decisions-for-someone-else/mental-capacity-act/). In some cases consent can also be obtained from a lasting power of attorney for health and welfare, or a court appointed deputy. Consent is usually obtained by a suitable member of staff discussing the [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) with the patient, their carer or the appropriate patient representative. The member of staff will then record the type of consent captured, along with some free text details providing more information about who provided the consent.

        For full details of this API resource see [RARecord-Consent-1](https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Consent-1)
      operationId: readConsent
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      responses:
        '200':
          description: Successful response.
          headers:
            Date:
              $ref: components/schemas/Date.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/readConsentResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  '/Consent/{consentID}':
    put:
      summary: Update consent details
      description: |-
        ## Overview
        Use this endpoint to update details regarding the patient's consent to share a [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) record, as well as how this was obtained. Consent may have been given by the patient or via a 'best interest decision' under the [Mental Capacity Act (2005)](https://www.nhs.uk/conditions/social-care-and-support-guide/making-decisions-for-someone-else/mental-capacity-act/). In some cases consent can also be obtained from a lasting power of attorney for health and welfare, or a court appointed deputy. Consent is usually obtained by a suitable member of staff discussing the [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) with the patient, their carer or the appropriate patient representative. The member of staff will then record the type of consent captured, along with some free text details providing more information about who provided the consent.

        For full details of this API resource see [RARecord-Consent-1](https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Consent-1)
      operationId: updateConsent
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
        - $ref: '#/components/parameters/consentID'
        - $ref: '#/components/parameters/If-Match'
      requestBody:
        description: Update record
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: components/schemas/updateConsent.yaml
            example:
              $ref: components/examples/updateConsent.json
      responses:
        '200':
          description: Successful response.
          headers:
            ETag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/updateConsentResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  /List:
    post:
      summary: Add impairments
      description: |-
        ## Overview
        Use this endpoint to create a list of impairments held within the [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) stored on the [NHS Spine](https://digital.nhs.uk/services/spine). These impairments will likely have been captured during the discussion between the clinician and the patient or their carer. Patients may however decline to provide details of their impairments if they do not want to share them. To capture an impairment the member of staff selects an impairment type and then provides additional information using a free text field. For more details regards impairments see [How the Reasonable Adjustment Flag works](https://digital.nhs.uk/services/reasonable-adjustment-flag#how-the-reasonable-adjustment-flag-works).

        For full details of this API resource see [CareConnect-RARecord-List-1](https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-RARecord-List-1)
      operationId: postList
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      requestBody:
        description: Create list
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
            example:
              $ref: components/examples/createList.json
      responses:
        '201':
          description: Successful response.
          headers:
            Etag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Location:
              $ref: components/schemas/Location.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/createListResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

    get:
      summary: Get impairments
      description: |-
        ## Overview
        Use this endpoint to read a list of impairments held within the [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) information stored on the [NHS Spine](https://digital.nhs.uk/services/spine). These impairments will likely have been captured during the discussion between the clinician and the patient or their carer. Patients may however decline to provide details of their impairments if they do not want to share them. To capture an impairment the member of staff selects an impairment type and then provides additional information using a free text field. For more details regards impairments see [How the Reasonable Adjustment Flag works](https://digital.nhs.uk/services/reasonable-adjustment-flag#how-the-reasonable-adjustment-flag-works).

        For full details of this API resource see [CareConnect-RARecord-List-1](https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-RARecord-List-1)
      operationId: readList
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/code'
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      responses:
        '200':
          description: Successful response.
          headers:
            Date:
              $ref: components/schemas/Date.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/readListResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  '/List/{listID}':
    put:
      summary: Update impairments
      description: |-
        ## Overview
        Use this endpoint to update a list of impairments held within the [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) information held on the [NHS Spine](https://digital.nhs.uk/services/spine). These impairments will likely have been captured during the discussion between the clinician and the patient or their carer. Patients may however decline to provide details of their impairments if they do not want to share them. To capture an impairment the member of staff selects an impairment type and then provides additional information using a free text field. For more details regards impairments see [How the Reasonable Adjustment Flag works](https://digital.nhs.uk/services/reasonable-adjustment-flag#how-the-reasonable-adjustment-flag-works).

        For full details of this API resource see [CareConnect-RARecord-List-1](https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-RARecord-List-1)
      operationId: updateList
      requestBody:
        description: Update list
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
            example:
              $ref: components/examples/updateList.json
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/listID'
      responses:
        '200':
          description: Successful response.
          headers:
            ETag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/updateListResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        '409':
          description: CONFLICT
          content:
            application/json:
              schema:
                type: object
                properties:
                  Date:
                    type: string
                    format: date-time
                    example: 'Tue, 23 Jul 2018 11:00:00 GMT'
                  Content-Type:
                    type: string
                    example: application/fhir+json
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  /Flag:
    post:
      summary: Add reasonable adjustments
      description: |-
        ## Overview
        Use this endpoint to create a [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) against the patient record on the [NHS Spine](https://digital.nhs.uk/services/spine). This will describe the adjustment that the patient needs and will either be a coded national adjustment as defined by [SNOMED CT](https://digital.nhs.uk/services/terminology-and-classifications/snomed-ct), or an adjustment which has been manually keyed by a clinician. To find out more about the different types of adjustments see [How the Reasonable Adjustment Flag works](https://digital.nhs.uk/services/reasonable-adjustment-flag#how-the-reasonable-adjustment-flag-works).


        For full details of this API resource see [RARecord-Flag-1](https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Flag-1/_history/0.0.5).
      operationId: postFlag
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      requestBody:
        description: Create flag
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: components/schemas/createFlag.yaml
            example:
              $ref: components/examples/createFlag.json
      responses:
        '201':
          description: Successful response.
          headers:
            ETag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Location:
              $ref: components/schemas/Location.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/createFlagResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n                  \n"

    get:
      summary: Get reasonable adjustments
      description: |-
        ## Overview
        Use this endpoint to view a [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) against the patient record on the [NHS Spine](https://digital.nhs.uk/services/spine). This will describe the adjustment that the patient needs and will either be a coded national adjustment as defined by [SNOMED CT](https://digital.nhs.uk/services/terminology-and-classifications/snomed-ct), or an adjustment which has been manually keyed by a clinician. To find out more about the different types of adjustments see [How the Reasonable Adjustment Flag works](https://digital.nhs.uk/services/reasonable-adjustment-flag#how-the-reasonable-adjustment-flag-works).


        For full details of this API resource see [RARecord-Flag-1](https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Flag-1/_history/0.0.5).
      operationId: readFlag
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      responses:
        '200':
          description: Successful response.
          headers:
            Date:
              $ref: components/schemas/Date.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              examples:
                0 flags:
                  summary: The response from a successful request (0 flags).
                  value:
                    $ref: components/examples/readZeroFlagResponse.json
                1 flag:
                  summary: The response from a successful request (1 flag).
                  value:
                    $ref: components/examples/readOneFlagResponse.json
                2 flags:
                  summary: The response from a successful request (2 flags).
                  value:
                    $ref: components/examples/readTwoFlagResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  '/Flag/{flagID}':
    put:
      summary: Update reasonable adjustments
      description: |-
        ## Overview
        Use this endpoint to update a [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) against the patient record on the [NHS Spine](https://digital.nhs.uk/services/spine). This will describe the adjustment that the patient needs and will either be a coded national adjustment as defined by [SNOMED CT](https://digital.nhs.uk/services/terminology-and-classifications/snomed-ct), or an adjustment which has been manually keyed by a clinician. You can also use this endpoint to delete an existing adjustment. To find out more about the different types of adjustments see [How the Reasonable Adjustment Flag works](https://digital.nhs.uk/services/reasonable-adjustment-flag#how-the-reasonable-adjustment-flag-works).


        For full details of this API resource see [RARecord-Flag-1](https://fhir.nhs.uk/STU3/StructureDefinition/RARecord-Flag-1/_history/0.0.5).
      operationId: updateFlag
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/flagID'
      requestBody:
        description: Update flag
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: components/schemas/updateFlag.yaml
            example:
              $ref: components/examples/updateFlag.json
      responses:
        '200':
          description: Successful response.
          headers:
            ETag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/fhir+json:
              example:
                $ref: components/examples/updateFlagResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        '409':
          description: CONFLICT
          content:
            application/json:
              schema:
                type: object
                properties:
                  Date:
                    type: string
                    format: date-time
                    example: 'Tue, 23 Jul 2018 11:00:00 GMT'
                  Content-Type:
                    type: string
                    example: application/fhir+json
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  /UnderlyingConditionList:
    post:
      summary: Add Underlying Condition
      description: |-
        ## Overview
        Use this endpoint to add underlying condition against the patient record on the [NHS Spine](https://digital.nhs.uk/services/spine).


      operationId: postUnderlyingCondition
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      requestBody:
        description: Add Underlying Condition
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: components/schemas/createUnderlyingConditionList.yaml
            example:
              $ref: components/examples/createUnderlyingConditionList.json
      responses:
        '201':
          description: Successful response.
          headers:
            ETag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Location:
              $ref: components/schemas/Location.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/createUnderlyingConditionListResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n                  \n"

    get:
      summary: Get underlying condition
      description: |-
        ## Overview
        Use this endpoint to view underlying conditions against the patient record on the [NHS Spine](https://digital.nhs.uk/services/spine). 
      operationId: readUnderlyingCondition
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      responses:
        '200':
          description: Successful response.
          headers:
            Date:
              $ref: components/schemas/Date.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              examples:
                0 UnderlyingConditionList:
                  summary: The response from a successful request (0 UnderlyingConditionList).
                  value:
                    $ref: components/examples/readZeroUnderlyingConditionListResponse.json
                1 UnderlyingConditionList:
                  summary: The response from a successful request (1 UnderlyingConditionList).
                  value:
                    $ref: components/examples/readOneUnderlyingConditionListResponse.json
                2 UnderlyingConditionList:
                  summary: The response from a successful request (2 UnderlyingConditionList).
                  value:
                    $ref: components/examples/readTwoUnderlyingConditionListResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  '/UnderlyingConditionList/{listID}':
    put:
      summary: Update underlying condition
      description: |-
        ## Overview
        Use this endpoint to update a list of underlying condition held within the [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) information held on the [NHS Spine](https://digital.nhs.uk/services/spine).
      operationId: updateUnderlyingCondition
      requestBody:
        description: Update UnderlyingCondition
        required: true
        content:
          application/fhir+json:
            schema:
              type: object
            examples:
              success:
                value:
                  $ref: components/examples/updateUnderlyingConditionList.json
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
        - $ref: '#/components/parameters/If-Match'
        - $ref: '#/components/parameters/listID'
      responses:
        '200':
          description: Successful response.
          headers:
            ETag:
              $ref: components/schemas/ETag.yaml
            Date:
              $ref: components/schemas/Date.yaml
            Last-Modified:
              $ref: components/schemas/Last-Modified.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              examples:
                Successful:
                  summary: The response from a successful request.
                  value:
                    $ref: components/examples/updateUnderlyingConditionListResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        '409':
          description: CONFLICT
          content:
            application/json:
              schema:
                type: object
                properties:
                  Date:
                    type: string
                    format: date-time
                    example: 'Tue, 23 Jul 2018 11:00:00 GMT'
                  Content-Type:
                    type: string
                    example: application/fhir+json
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  /ThresholdCode:
    get:
      summary: Get ThresholdCode
      description: |-
        ## Overview
        Use this endpoint to view ThresholdCode  against the patient record on the [NHS Spine](https://digital.nhs.uk/services/spine). 
      operationId: readThresholdCode
      parameters:
        - $ref: '#/components/parameters/patient'
        - $ref: '#/components/parameters/status'
        - $ref: '#/components/parameters/category'
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
      responses:
        '200':
          description: Successful response.
          headers:
            Date:
              $ref: components/schemas/Date.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              examples:
                0 ThresholdCode:
                  summary: The response from a successful request (0 ThresholdCode).
                  value:
                    $ref: components/examples/readZeroThresholdCodeResponse.json
                1 ThresholdCode:
                  summary: The response from a successful request (1 ThresholdCode).
                  value:
                    $ref: components/examples/readOneThresholdCodeResponse.json
                2 ThresholdCode:
                  summary: The response from a successful request (2 ThresholdCode).
                  value:
                    $ref: components/examples/readTwoThresholdCodeResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

  /$removerarecord:
    post:
      summary: Remove Reasonable Adjustment Flag record
      description: |
        ## Overview
        Use this endpoint to remove a [Reasonable Adjustment Flag](https://digital.nhs.uk/services/reasonable-adjustment-flag) from the [NHS Spine](https://digital.nhs.uk/services/spine).  To remove a flag you must provide a reason for it being removed, for example the flag may have been created in error, or the flag may no longer apply to the patient. 

        For a patient it is represented as [RARecord-RemovalReason-1](https://fhir.nhs.uk/STU3/CodeSystem/RARecord-RemovalReason-1). This triggers the system to inactivate all Reasonable Adjustment Flag resources contained within the patient record.
      operationId: removeRecord
      requestBody:
        description: Remove Reasonable Adjustment Flag record
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: components/schemas/removerarecord.yaml
            example:
              $ref: components/examples/removerarecord.json
      parameters:
        - $ref: '#/components/parameters/BearerAuthorization'
        - $ref: '#/components/parameters/RoleId'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/RequestID'
        - $ref: '#/components/parameters/If-Match'
      responses:
        '200':
          description: Successful response.
          headers:
            Date:
              $ref: components/schemas/Date.yaml
            Content-Type:
              $ref: components/schemas/Content-Type.yaml
          content:
            application/json:
              example:
                $ref: components/examples/removerarecordResponse.json
        '400':
          description: Invalid parameters.
          content:
            application/fhir+json:
              schema:
                $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
              examples:
                invalid-nhsNumber:
                  summary: Invalid NHS number for patient supplied.
                  value:
                    resourceType: OperationOutcome
                    issue:
                      - severity: error
                        code: value
                        details:
                          coding:
                            - system: 'https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1'
                              code: INVALID_NHS_NUMBER
                              display: Invalid NHS number
        4XX:
          description: "Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).\nThere are a number of possible error codes that can be returned along with a more detailed description in the `display` field.\nThere are general outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. \t|\n| UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |\n| UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |\n| RESOURCE_NOT_FOUND         | 404           | The resource was not found. |\n| INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS number is presented which is not a valid NHS number. |\n| INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |\n\nUpdate outcomes:\n\n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |\n| RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |\n| FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |\n| VALIDATION_ERROR           | 400           | This it the \"default\" error thrown when no others are applicable. |\n| INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |\n| MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.\t|\n| INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |\n| UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |\n| TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |\n| TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |\n| ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |\n\nPolling outcomes:\n  \n| Code                       | Response Code | Description                                   |\n| -------------------------- | ------------- | --------------------------------------------- |\n| POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.\t|\n| POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |\n"

components:
  parameters:
    nhsNumber:
      name: nhsNumber
      in: query
      required: true
      description: ID number of a patient
      schema:
        type: object
        properties:
          name:
            type: string
            example: nhsNumber
          valueString:
            type: string
            example: '999999998'
    removalReason:
      name: removalReason
      in: query
      required: true
      description: Code recording Removal Reason
      schema:
        type: object
        properties:
          name:
            type: string
            example: removalReason
          valueCodeableConcept:
            type: object
            properties:
              coding:
                type: array
                items:
                  type: object
                  properties:
                    system:
                      type: string
                      example: 'https://fhir.nhs.uk/STU3/CodeSystem/RARecord-RemovalReason-1'
                    code:
                      type: string
                      example: DoesntApply
                    display:
                      type: string
                      example: The Reasonable Adjustment Flag no longer applies to the patient
    supportingComment:
      name: supportingComment
      in: query
      required: true
      description: Comment supporting Removal Reason
      schema:
        type: object
        properties:
          name:
            type: string
            example: supportingComment
          valueString:
            type: string
            example: No longer applies
    If-Match:
      name: If-Match
      in: header
      required: true
      description: |
        Latest known version identifier enclosed in quotes preceded by `W/`.
        Send the value of the patient's `ETag` response header on patient retrieval when updating a patient.
        This is to ensure that any updates are applied against an up-to-date version of the patient resource.
      schema:
        type: string
        pattern: "^W/\"[0-9]+\"$"
        example: 'W/"2"'
    consentID:
      name: consentID
      in: path
      required: true
      description: The id of the record. To retrieve the consentID, you need to do a GET /Consent first. The successful response from GET /Consent endpoint contains the consentID. See the example of successful response in [Get consent details](https://digital.nhs.uk/developer/api-catalogue/reasonable-adjustment-flag-fhir#api-Endpoints-readConsent) section. See the example below to know the consentID from that response.
      schema:
        type: string
        example: '5900026175.11eccc9b-4a6f-4467-a76b-1b8a82bafd65'
    flagID:
      name: flagID
      in: path
      required: true
      description: The id of the flag. To retrieve the flagID, you need to do a GET /Flag first. The successful response from GET /Flag endpoint contains the flagID. See the example of successful response in [Get reasonable adjustments](https://digital.nhs.uk/developer/api-catalogue/reasonable-adjustment-flag-fhir#api-Endpoints-readFlag) section. See the example below to know the flagID from that response.
      schema:
        type: string
        example: '5900026175.b1fe6cc0-7bf5-453c-a396-1ae97cfad72a'
    listID:
      name: listID
      in: path
      required: true
      description: The id of the list. To retrieve the listID, you need to do a GET /List first. The successful response from GET /List endpoint contains the listID. See the example of successful response in [Get impairments](https://digital.nhs.uk/developer/api-catalogue/reasonable-adjustment-flag-fhir#api-Endpoints-readList) section. See the example below to know the listID from that response.
      schema:
        type: string
        example: '5900026175.3d368fbe-e621-4c0b-be74-9a59b4f0e467'
    patient:
      name: patient
      in: query
      required: true
      description: 'The patient''s NHS number. The primary identifier of a patient, unique within NHS England and Wales. Always 10 digits and must be a [valid NHS number](https://datadictionary.nhs.uk/attributes/nhs_number.html).'
      schema:
        type: string
        example: '5900026175'
    status:
      name: status
      in: query
      required: true
      description: The status of the patient resource. Active or Inactive.
      schema:
        type: string
        example: active
    category:
      name: category
      in: query
      required: true
      description: The category of the resource being interacted with.
      schema:
        type: string
        example: 'https://fhir.nhs.uk/STU3/CodeSystem/RARecord-FlagCategory-1|NRAF'
    code:
      name: code
      in: query
      required: true
      description: code
      schema:
        type: string
        example: 'http://snomed.info/sct|1094391000000102&_format=json'
    RoleId:
      name: NHSD-Session-URID
      in: header
      required: false
      description: |
        The user role ID (URID) for the current session. Also known as a user role profile ID (URPID).

        If you are using User-restricted RESTful APIs - NHS login combined authentication and authorisation, See [determine the user's role](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-combined-authentication-and-authorisation#step-7-determine-the-user-s-role) guidance.
        If you are using User-restricted RESTful APIs - NHS login separate authentication and authorisation, See [determine the user's role](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-cis2-separate-authentication-and-authorisation#step-9-determine-the-user-s-role) guidance.
      
        This field is optional.

      schema:
        type: string
        pattern: '^[0-9]+$'
        example: '555021935107'
    BearerAuthorization:
      name: Authorization
      in: header
      required: false
      description: |
        An [OAuth 2.0 bearer token](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis).

        **Note: This parameter is required unless interacting with the Sandbox.**
      schema:
        type: string
        format: '^Bearer\ [[:ascii:]]+$'
        example: 'Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM'
    CorrelationID:
      name: X-Correlation-ID
      in: header
      required: false
      description: |
        A globally unique identifier (GUID) for the request, which we use to trace the request if you contact our helpdesk.
        Mirrored back in a response header.
        Avoid characters.
      schema:
        type: string
        example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
    RequestID:
      name: X-Request-ID
      in: header
      required: false
      description: |
        A globally unique identifier (GUID) for the request, which we use to de-duplicate repeated requests.
        Must be a universally unique identifier (UUID) (ideally version 4).
        If you re-send a failed request, use the same value in this header.
        Mirrored back in a response header.

        **Required in all environments except sandbox.**
      schema:
        type: string
        pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
        example: 60E0B220-8136-4CA5-AE46-1D97EF59D068
  schemas:
    adjustmentCategoryExtension:
      $ref: components/schemas/adjustmentCategoryExtension.yaml
    createConsent:
      $ref: components/schemas/createConsent.yaml
    createFlag:
      $ref: components/schemas/createFlag.yaml
    createUnderlyingConditionList:
      $ref: components/schemas/createUnderlyingConditionList.yaml
    createList:
      $ref: components/schemas/createList.yaml
    errorCode:
      $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/errorCode.yaml
    nhsNumber:
      $ref: components/schemas/nhsNumber.yaml
    operationOutcome:
      $ref: https://raw.githubusercontent.com/NHSDigital/oas-shared-fragments/master/spine-core/errors/operationOutcome.yaml
    provenanceExtension:
      $ref: components/schemas/provenanceExtension.yaml
    removalReason:
      $ref: components/schemas/removalReason.yaml
    removalReasonExtension:
      $ref: components/schemas/removalReasonExtension.yaml
    removerarecord:
      $ref: components/schemas/removerarecord.yaml
    supportingComment:
      $ref: components/schemas/supportingComment.yaml
    updateFlag:
      $ref: components/schemas/updateFlag.yaml
    updateList:
      $ref: components/schemas/updateList.yaml