# This is an OpenAPI Specification (https://swagger.io/specification/)
# for the Innunisation History API
# owned by NHS Digital (https://digital.nhs.uk/)
openapi: "3.0.0"
x-nhs-api-spec-guid: 1b22efff-7b41-4fa0-9146-dc87686a7b5c
info:
  version: 1.0.0
  title: Covid Medical Exemption - FHIR API
  license:
    name: MIT
  contact:
    name: NHS Digital API Management
    url: 'https://digital.nhs.uk/developer/help-and-support'
    email: api.management@nhs.net
  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.</p></div>
            </div>
        </div>
    </div>
      
    ## Overview
    Use this API to access a patient’s coronavirus (COVID-19) medical exemption status.

    You can:
    - get a patient's COVID-19 medical exemption status, based on their NHS number

    You get the following data:
    - current COVID-19 medical exemption status
    - embedded Patient demographic details, including date of birth.

    The patient demographic details might differ from those held in the [Personal Demographics Service (PDS)](https://digital.nhs.uk/services/demographics).
    To get demographic details from PDS, use the [Personal Demographics Service FHIR API](https://digital.nhs.uk/developer/api-catalogue/personal-demographics-service-fhir).

    ### Data standards

    This API uses the FHIR standard, and includes the resources:
      * [Bundle](https://www.hl7.org/fhir/bundle.html)
      * [Patient](https://www.hl7.org/fhir/patient.html)
      * [QuestionnaireResponse](https://www.hl7.org/fhir/questionnaireresponse.html)

    It references resources:
      * [Questionnaire](https://www.hl7.org/fhir/questionnaire.html) specifically [COVID-19 Vaccination Medical Exemption Questionnaire](https://simplifier.net/resolve?target=simplifier&scope=uk.nhsdigital.r4&canonical=https://fhir.nhs.uk/Questionnaire/COVIDVaccinationMedicalExemption)

    ### Data availability, timing and quality
    All exemption records are verified to ensure the NHS number is correct before making them available via the API.

    In most cases this is automatic, and the record is available within 48 hours of the exemption being recorded, sometimes sooner.

    Where automated NHS number verification fails, we verify the NHS number manually, which can take longer.

    In a very small number of cases, we are unable to verify the NHS number, and we do not make the medical exemption available at all.

    ## Who can use this API
    This API:
    - is only for use by patient-facing applications
    - is only for non-clinical use
    - 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.
    To do this, [contact us](https://digital.nhs.uk/developer/help-and-support).

    You must do this before you can go live (see ‘Onboarding’ below).

    ## API status and roadmap
    This API is [retired](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) and not available for 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/?tag=covid-medical-exemptions-api).

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

    It conforms to the [FHIR](https://digital.nhs.uk/developer/guides-and-documentation/our-api-technologies#fhir) global standard for health care data exchange, specifically to [FHIR R4 (v4.0.1)](https://hl7.org/fhir/r4/), except that it does not support the [capabilities](http://hl7.org/fhir/R4/http.html#capabilities) interaction.

    It includes some country-specific FHIR extensions, which conforms to [FHIR UK Core](https://digital.nhs.uk/services/fhir-uk-core), specifically [fhir.r4.ukcore.stu1 0.5.1](https://simplifier.net/packages/fhir.r4.ukcore.stu1/0.5.1).

    You do not need to know much about FHIR to use this API - FHIR APIs are just RESTful APIs that follow specific rules.
    In particular:
    - resource names are capitalised and singular, and use US spellings, for example `/QuestionnaireResponse` not `/questionnaireresponse`
    - array names are singular, for example `entry` not `entries` 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

    There are [libraries and SDKs available](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#fhir-libraries-and-sdks) to help with FHIR API integration.

    ## 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).

    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 has two access modes: 
    * application-restricted access
    * user-restricted access
    
    ### Application-restricted access
    This access mode is [application-restricted](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#application-restricted-apis), meaning we authenticate the calling application but not the end user.
    
    To use this access mode, use the following security pattern:
    * [Application-restricted RESTful API - signed JWT authentication](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/application-restricted-restful-apis-signed-jwt-authentication)
    
    ### User-restricted access
    Use this [user-restricted access mode](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation#user-restricted-apis) if the end user is a patient:
    * the end user must have their identity verified to 'high' (P9) level
    * the NHS number in the request must match the NHS number in the NHS login account
    
    To use this access mode, use the following security pattern:
    * [User-restricted RESTful APIs - NHS login separate authentication and authorisation](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation)

    ## Environments and testing
    | Environment       | Base URL                                                                |
    | ----------------- | ----------------------------------------------------------------------- |
    | Sandbox           | `https://sandbox.api.service.nhs.uk/covid-medical-exemptions/FHIR/R4`   |
    | Integration test  | `https://int.api.service.nhs.uk/covid-medical-exemptions/FHIR/R4`       |
    | Production        | `https://api.service.nhs.uk/covid-medical-exemptions/FHIR/R4`           |

    ### 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 open access, so does not allow you to test authorisation

    For details of sandbox test scenarios, or to try out the sandbox using our 'Try this API' feature, see the documentation for each endpoint.

    Alternatively, you can try out the sandbox using our Postman collection:

    ### Integration testing
    Our [integration test environment](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing):
    * is for formal integration testing
    * includes authorisation

    Currently, the integration test environment returns a single static response, the same one as the sandbox environment - regardless of what request parameters you send.
    In due course we will change it to support more scenarios.

    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

    This API is [retired](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses) and not available for use.

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

servers:
  - url: 'https://sandbox.api.service.nhs.uk/covid-medical-exemptions/FHIR/R4'
    description: Sandbox environment.
  - url: 'https://int.api.service.nhs.uk/covid-medical-exemptions/FHIR/R4'
    description: Integration test environment.
  - url: 'https://api.service.nhs.uk/covid-medical-exemptions/FHIR/R4'
    description: Production environment.
paths:
  /QuestionnaireResponse:
    get:
      summary: Get current COVID-19 medical exemption status
      operationId: get-covid-medical-exemption
      description: |
        Given an NHS number, get the patient's current COVID-19 medical exemption status.
        Also returns the patient's demographic details, as captured at the point of the exemption decision being made.

        ## Sandbox testing
        You can test the following scenarios in our sandbox environment:

        Sample outputs are generated using any patient.identifer where the remainder of dividing by 5.  (i.e. id % 5 == X)

        | Scenario                             | Request                                                                              | Response                                                |
        | ------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------- |
        | No Current Exemption                 | `patient.identifier` = <code>https://fhir.nhs.uk/Id/nhs-number&#124;<X%5==0></code>  | HTTP Status 200 with empty bundle in response body      |
        | Exempt from Vaccination              | `patient.identifier` = <code>https://fhir.nhs.uk/Id/nhs-number&#124;<X%5==1></code>  | HTTP Status 200 with exemption data in response body    |
        | Exempt from Vaccination and Testing  | `patient.identifier` = <code>https://fhir.nhs.uk/Id/nhs-number&#124;<X%5==2></code>  | HTTP Status 200 with exemption data in response body    |
        | Declined for Vaccination             | `patient.identifier` = <code>https://fhir.nhs.uk/Id/nhs-number&#124;<X%5==3></code>  | HTTP Status 200 with exemption data in response body    |
        | Declined for Vaccination and Testing | `patient.identifier` = <code>https://fhir.nhs.uk/Id/nhs-number&#124;<X%5==4></code>  | HTTP Status 200 with exemption data in response body    |

        You can try out the sandbox using the 'Try this API' feature on this page.
      parameters:
        - name: patient.identifier
          in: query
          description: |
            The patient's NHS number.
            Expressed as `<type>|<value>` where `<type>` must be `https://fhir.nhs.uk/Id/nhs-number` and `<value>` must be a [valid NHS number](https://www.datadictionary.nhs.uk/attributes/nhs_number.html).
          required: true
          schema:
            type: string
            pattern: ^https:\/\/fhir\.nhs\.uk\/Id\/nhs-number\|[0-9]+$
            example: "https://fhir.nhs.uk/Id/nhs-number|9912003888"
        - name: questionnaire
          in: query
          description: |
            The questionnaire to be consumed
          schema:
            type: string
            example: "https://fhir.nhs.uk/Questionnaire/COVIDVaccinationMedicalExemption"
        - name: Authorization
          in: header
          description: |
            An OAuth 2.0 bearer token, obtained using our [NHS login pattern](https://digital.nhs.uk/developer/guides-and-documentation/security-and-authorisation/user-restricted-restful-apis-nhs-login-separate-authentication-and-authorisation).
          schema:
            type: string
            pattern: ^Bearer\ .+$
            example: Bearer g1112R_ccQ1Ebbb4gtHBP1aaaNM
        - name: X-Correlation-ID
          in: header
          required: false
          description: |
            An optional ID which you can use to track transactions across multiple systems. It can take any value, but we recommend avoiding `.` characters.

            Mirrored back in a response header.
          schema:
            type: string
            format: uuid
            example: "11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA"
      responses:
        '200':
          description: |
            The request was valid, and the response contains a current exemption and associated patient details.
            If there are no exemptions for the given NHS number, the response bundle will be empty.
          headers:
            X-Correlation-Id:
              $ref: components/schemas/XCorrelationId.yaml
          content:
            application/fhir+json:
              schema:
                $ref: "#/components/schemas/Bundle"
              example:
                $ref: "components/examples/exempt-vaccine-and-testing.fhir.json"
        '4XX':
          description: |
            An error occurred as follows:

            | HTTP status | Error code                 | Description                                                          |
            | ----------- | -------------------------- | -------------------------------------------------------------------- |
            | 400         | `processing`               | Missing or invalid NHS number                                        |
            | 400         | `processing`               | Missing or invalid questionnaire                                     |
            | 401         | `processing`               | Missing or invalid ID token                                          |
            | 401         | `processing`               | Missing or invalid OAuth 2.0 bearer token                            |
            | 401         | `processing`               | NHS number in request doesn't match NHS number in NHS login account  |

            For details see the `diagnostics` field.

          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/OperationOutcome'
              example:
                $ref: 'components/examples/OperationOutcome.json'

# components object must be present for spec rendering to work in Bloomreach, even if the spec has no components
components:
  schemas:
    Bundle:
      $ref: components/schemas/Bundle.schema.yaml
    QuestionnaireResponse:
      $ref: components/schemas/QuestionnaireResponse.schema.yaml
    OperationOutcome:
      $ref: components/schemas/OperationOutcome.yaml