openapi: 3.0.0
x-nhs-api-spec-guid: bf6758a5-b731-4640-876a-f7ad56e36029
x-meta:
  service_name: "eyecare-electronic-referrals-service"
  short_service_name: "eye"
  product_display_name: "Eyecare Referral API"
  service_base_path: "eyecare-referrals"
  product_description: "A simple API to allow details of a new eyecare referral to be passed to an Eyecare electroinc referral system (EeRS) from an Optometry patient management system."
  pipeline_name_prefix: "Eyecare-Referrals"
x-spec-publication:
  operation-order:
  - operations:
    - method: POST
      path: /referrals
    - method: GET
      path: /referral/{referralID}/status
info:
  title: Eyecare electronic Referral API
  version: '1.0.0'
  contact:
    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 standard is <a href="https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses">retired</a>, meaning it is not being maintained and should not be used.</p>
                  <p class="nhsd-t-body">Depending on your situation, you might be able to use the <a href="https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir">e-Referral Service FHIR API</a> instead.</p>
                  <p class="nhsd-t-body">If you have any other queries, contact us at <a href="mailto:england.eyecare-transformation@nhs.net">england.eyecare-transformation@nhs.net</a>.</p>
                </div>
            </div>
        </div>
    </div>
    
    ## Overview
    
    Use this API standard to pass details of a new eyecare referral from an Optometry Patient Management System (Optometry PMS) to an Eyecare electronic Referral system (EeRS).
    
    The API standard supports sending key referral information (including the GOS18 data items) from an optometrist to NHS services via an EeRS. This is important for engaging optometrists in digital referrals into the NHS, and eliminate double-keying of information documented as part of a sight test or optical consultation.

    Each NHS region will procure an EeRS system from the [Dynamic Purchasing System (DPS) for Electronic Eyecare Referral Systems (EeRS)](https://www.nhsx.nhs.uk/key-tools-and-info/procurement-frameworks/dynamic-purchasing-system-electronic-eyecare-referral-systems/). 
    Each EeRS system receives referrals using this API standard and provides its own endpoint for this service.
    
    This API standard is a published specification only. Therefore you, as an Optometry PMS developer, implement and integrate it directly with each EeRS, not via our services. Therefore, the sending Optometry PMS system needs to link to each EeRS eyecare e-referral endpoint that conforms to the API standard.  
    
    ### Building the API standard into an Optometry PMS
    
    Use the following steps to implement the API standard as a sending Optometry PMS to a specific EeRS:

    1. Identify the data fields in your system that correspond to the data fields in the specification.
    2. Ask the EeRS supplier to provide their API endpoint.
    3. Ask the EeRS supplier you are integrating with to provide a system-to-system API key. 
    4. Develop your system to connect to the API and send the API key with the data payload to that EeRS endpoint. 
    5. Design a way of initiating the referral process from the Optometry PMS – ideally using a “refer via EeRS” button in the right part of the workflow in your PMS system
    6. Test that referral process is working from your Optomotry PMS to the endpoint with the EeRS, and check with a clinician that the right data fields are coming across inside the EeRS system. 

    <section class="nhsd-m-emphasis-box nhsd-m-emphasis-box--important nhsd-!t-margin-bottom-6" aria-label="Important Information">
        <div class="nhsd-a-box nhsd-a-box--border-yellow">                <div class="nhsd-m-emphasis-box__image-box">
                    <figure class="nhsd-a-image">
                        <picture class="nhsd-a-image__picture">
                                    <img src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiIHN0YW5kYWxvbmU9Im5vIj8+CjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAyNS4xLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT48c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIGlkPSJMYXllcl8xIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCAxNDAgMTQwOyIgdmVyc2lvbj0iMS4xIiB2aWV3Qm94PSIwIDAgMTQwIDE0MCIgeD0iMHB4IiB4bWw6c3BhY2U9InByZXNlcnZlIiB5PSIwcHgiPgo8c3R5bGUgdHlwZT0idGV4dC9jc3MiPgoJLnN0MHtkaXNwbGF5Om5vbmU7fQoJLnN0MXtkaXNwbGF5OmlubGluZTtmaWxsOiMyMzFmMjA7fQoJLnN0MntmaWxsOiMyMzFmMjA7fQoJLnN0M3tmaWxsOm5vbmU7c3Ryb2tlOiMyMzFmMjA7c3Ryb2tlLXdpZHRoOjEuOTI7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7c3Ryb2tlLWxpbmVqb2luOnJvdW5kO3N0cm9rZS1taXRlcmxpbWl0OjEwO30KCS5zdDR7ZmlsbDojMjMxZjIwO30KCS5zdDV7ZmlsbDojMjMxZjIwO30KCS5zdDZ7ZmlsbDpub25lO3N0cm9rZTojMjMxZjIwO3N0cm9rZS13aWR0aDo1O3N0cm9rZS1taXRlcmxpbWl0OjEwO30KPC9zdHlsZT4KPGcgY2xhc3M9InN0MCI+Cgk8cGF0aCBjbGFzcz0ic3QxIiBkPSJNNzAsNi45NWw1NCwzMS41djYzLjExbC01NCwzMS41bC01NC0zMS41VjM4LjQ1TDcwLDYuOTUgTTcwLDBMMTAsMzV2NzBsNjAsMzVsNjAtMzVWMzVMNzAsMEw3MCwweiIvPgo8L2c+CjxnPgoJPHBhdGggY2xhc3M9InN0MiIgZD0iTTEwOS44NiwzOS44NXY1NUg4NS43Yy0zLjA2LDAtNS4xNCwzLjA2LTcuMDgsNWgtMTcuNWMtMS45NC0xLjk0LTQuMDMtNS03LjA4LTVIMjkuODd2LTU1aDI1ICAgYzUuMjgsMCwxMC44MywxLjMyLDE1LDQuNzljNC4xNy0zLjQ3LDkuNzItNC43OSwxNS00Ljc5SDEwOS44NnogTTY0Ljg2LDU0Ljg1YzAtMy44OS03LjIyLTUtMTAtNWgtMTV2MzVoMTMuNzUgICBjNS42MiwwLDcuNTcsMC42OSwxMS4yNSw1VjU0Ljg1eiBNOTkuODYsNDkuODVoLTE1Yy0yLjc4LDAtMTAsMS4xMS0xMCw1djM1YzMuNjgtNC4zMSw1LjYyLTUsMTEuMjUtNWgxMy43NVY0OS44NXoiLz4KPC9nPgo8L3N2Zz4K" 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">For a non-technical overview of how to build software that deals with referrals and bookings, see&nbsp;<a onclick="logGoogleAnalyticsEvent('Link click','General','/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings');" href="/developer/guides-and-documentation/building-healthcare-software/referrals-and-bookings" onkeyup="return vjsu.onKeyUp(event)" class="nhsd-a-link">Building healthcare software - referrals and bookings</a>.</p></div>            </div>
        </div>
    </section>
    
    ## Who can use this API

    This API standard can be provided by any EeRS as procured regionally.  It can be used by any Optometry PMS to allow an optometrist to send a referral into a specific EeRS system. Integrated Care Systems may require each Optometry system in use in their area to link to their specific EeRS system.
    
    ## Status and roadmap
 
    This API standard is [retired](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning it is not being maintained and should not be used.
    
    Depending on your situation, you might be able to use the [e-Referral Service FHIR API](https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir) instead.
    
    If you have any other queries, contact us at [england.eyecare-transformation@nhs.net](mailto:england.eyecare-transformation@nhs.net).
    
    ### Version control

    We use HTTP headers to allow you to specify the API version you want to call.

    In general, once an API is in production (meaning it has exited beta) we avoid making any breaking changes. That means we might add new data fields or add new valid values to code sets, but we won't remove any mandatory fields or change the semantic meaning of any existing fields or code sets.

    If we ever do need to make breaking changes to an in production API, we will continue to use HTTP headers to allow you to specify the API version you want to call. We'll do this in a backwards-compatible way.

    This spec version:            1.0.0

    ## Technology

    This API standard uses RESTful technology, as described in our guidance [here](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).
    
    ## Network access
    
    EeRS supplier API endpoints that conform to this API standard are available on the internet.

    ## Security and authorisation
    
    All communications must be encrypted using HTTP(S).

    Each EeRS endpoint must be secured via an API key included in the HTTP header. Note that we recommend the use of an 128-bit API key as a minimum.
    Liaise with the EeRS supplier you are integrating with, to get an API key for their endpoint configuration.

    ## Onboarding

    Liaise with NHSX for onboarding your service into live operation. Please contact NHSX at [digital.podac@nhsx.nhs.uk](mailto:digital.podac@nhsx.nhs.uk).
    
    ## 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:
  # Added by API Auto Mocking Plugin

  - description: SwaggerHub API Auto Mocking - RW
    url: https://virtserver.swaggerhub.com/Sphinx/Eyecare/1.0
  - url: 'http://localhost:3000'
paths:
  '/referrals':
    post:
      summary: 'Create a referral'
      operationId: post-referrals  
      parameters: 
        - $ref: '#/components/parameters/VersionHeader'
        - $ref: '#/components/parameters/Authorization'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: 'components/schemas/Response.yaml'
              example:
                referralID: 123e4567-e89b-12d3-a456-426614174000
                referralURL: >-
                  https://someEeRSSystem/referrals/123e4567-e89b-12d3-a456-426614174000
                referralStatus: incomplete
          headers:
            Accept-Version:
              description: The version number of the API you wish to call.
              schema:
                type: string
                example: 1.0.0
        '4XX':
          description: |
            An error occurred as follows:
              
            | HTTP status | errorMessage                                               | errorCode     | Scenario                                                |
            | ----------- |----------------------------------------------------------- |-------------- | ------------------------------------------------------- |
            | 400         | Malformed JSON                                             | E0001         | JSON could not be parsed for processing. It is invalid. |
            | 400         | Empty JSON body                                            | E0002         | No JSON was received in the request body.               |
            | 400         | A null value was submitted in one or more required fields.  The fields are [insert field list]. | E0008     | No value was submitted in a mandatory field. | 
            | 401         | Authentication failed                                      | E0010         | Either the API-KEY is invalid or the values in the ODS and GOCNumber fields failed authentication. |
            | 422         | ODS Code Invalid                                           | E0006         | ODS Code supplied not matched in EeRS system.For example, the formatting may not be valid, or it may not have matched a record in the register of ODSCodes held in the receiving system. |
            | 422         | Registrant Number invalid                                  | E0007         | The value supplied in the RegistrantNumber field is not valid as defined by the receiving system. For example, the formatting may not be valid, or it may not have matched a record in the register of GOC and GMC numbers held in the receiving system. |
            | 422         | A data type could not be converted                         | E0009         | This error is used when the conversion to the target data type cannot be made. |
      
          content:
            application/json:
              schema:
                $ref: 'components/schemas/Response.yaml'
              example:
                errorMessage: Malformed JSON
                errorCode: E0001
          headers:
            Accept-Version:
              description: The version number of the API you wish to call.
              schema:
                type: string
        '500':
          description: Internal Server Error
      description: >-
        Sends a new referral into the EeRS

         ### Create a new referral in the EeRS

          **Step 1**: The cinician user decides to create a referral and clicks “refer via EeRS” or similar on the Optometry PMS system

          **Step 2**: Optometry PMS gathers the data payload to send via the API
          
          **Step 3**: Optometry PMS identifies the EeRS supplier API to call based on the optometry practice where the practitioner has clicked ‘create EeRS referral’
          
          **Step 4**: Optometry PMS initiates API by sending API key to the EeRS in question with the data payload
          
          **Step 5**: EeRS provides a response 201 with a URL - or an error message
          
         ### Complete the referral in the EeRS 

          **Step 1**: Optometry PMS launches the URL for the user in a browser
          
          **Step 2**: The user can now see the data rendered in the EeRS, and can complete the referral.
          
          **Step 3**: The user completes the referral using the EeRS.
          
          ### Optometry PMS sender guidance

          If there is no value in your Optometry PMS for a non-mandatory nullable field do either one of the following:
            - exclude that field from the JSON
            - use JSON NULL to represent an empty field rather than empty string. 
          
          ### EeRS provider guidance

          Any non-mandatory field will either be included as JSON null or not included at all from the sending Optometry PMS system. When saving a new referral initialise these fields to null in your system.

      requestBody:
        content:
          application/json:
            schema:
              $ref: 'components/schemas/Referral.yaml'
            example:
              $ref: 'components/examples/Referral.json'
  '/referral/{referralID}/status':
    parameters:
      - schema:
          type: string
        name: referralID
        description: The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID.
        example: "123e4567-e89b-12d3-a456-426614174000"
        in: path
        required: true
    get:
      summary: Get referral status
      parameters: 
        - $ref: '#/components/parameters/VersionHeader'
        - $ref: '#/components/parameters/Authorization'
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: 'components/schemas/StatusResponse.yaml'
              example:
                referralStatus: incomplete
          headers:
            Accept-Version:
              description: The version number of the API you wish to invoke.
              schema:
                type: string
                example: "1.0.0"
       
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: 'components/schemas/StatusResponse.yaml'
              example:
                errorMessage: The request was malformed and couldn't be processed
                errorCode:  E0001
          headers:
            Accept-Version:
              description: The version number of the API you invoked.
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: 'components/schemas/StatusResponse.yaml'
              example:
                errorMessage: The API-KEY is invalid
                errorCode:  E0010
          headers:
            Accept-Version:
              description: The version number of the API you invoked.
              schema:
                type: string
        '404':
          description: Referral with given ID not found
          content:
            application/json:
              schema:
                $ref: 'components/schemas/StatusResponse.yaml'
              example:
                errorMessage: ReferralID cannot be found by the receiving system 
                errorCode:  E0005        
          headers:
            Accept-Version:
              description: The version number of the API you invoked.
              schema:
                type: string
        '500':
          description: Internal Server Error        

      operationId: get-referral-referralID-status

      description: >-
        Returns the status of the referral with the given ID

        A status update can be initiated by a clinician or admin, or set to be initiated automatically for all referrals as desired.

          **Step 1**: PMS system requests a status check to a specific referral ID using the same API key as for the referral

          **Step 2**: EeRS supplier provides response 200 with the status - or an error message          
security:
  - apikey: []
components:
  securitySchemes:
    apikey:
      type: apiKey
      in: header
      name: api-key
  parameters:
    VersionHeader:
      name: Accept-Version
      description:  The version number of the API you wish to call.
      in: header
      schema:
        type: string
        example: 1.0.0
    Authorization:
      name: api-key
      description:  The API Key associated with the calling API consumer.
      in: header
      schema:
        type: string
        example: KdsASD78FA5Sjl342kfwreas