openapi: 3.0.0
x-nhs-api-spec-guid: bf6758a5-b731-4640-876a-f7ad56e36029
x-meta:
  service_name: "eyecare-e-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 referral to be passed to an Eyecare e-referral system (EeRS) from an Optometry patient management system."
  pipeline_name_prefix: "Eyecare-Referrals"
info:
  title: Eyecare Referral API
  version: '1.0'
  contact:
    url: 'https://digital.nhs.uk/developer/help-and-support'
    email: api.management@nhs.net
  description: |
    ## Overview
    
    Use this API standard to pass details of a new referral from an Optometry Patient Management System (Optometry PMS) to an Eyecare e-referral system (EeRS).
    
    The goal of the API standard is to pre-populate clinical, user and patient information from an Optometry PMS to an EeRS. 

    The API standard supports auto-population of GOS18 and associated referral data from the Optomoetry PMS. 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.  
    The details on the EeRS suppliers and their endpoints is here [insert link to NHSX site here] 
    
    You can:
    - transfer key clinical, patient and practitioner information associated with making a referral to NHS health services via an EeRS
    - auto-populate GOS18 and associated referral data from the Optometry PMS

    
    ## Who can use this API
    
    This API standard can be used by any Optometry PMS to allow an Optometrist to send a referral into a specific EeRS system. Integrated Care Systems require each Optometry system in use in their area to link to their specific EeRS system.
    
    ## API status and roadmap

    This API standard is in [Beta](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#api-status), meaning:
      * it is available for production use
      * we might make breaking changes, but only if we cannot avoid it, and we will give an advance notice
    
    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=allexceptdone&tag=eyecare-e-referral-api&deleted=0#controls).
    
    If you have any other queries, please contact us at bookingandreferrals@nhs.net.
    
    ## Technology
    This API standard uses HTTP POST to submit data.
    
    ## Network access
    
    EeRS supplier API endpoints that conform to this API standard are available on the internet.

    ## Security and authorisation
    
    Each EeRS endpoint must be secured via an API key. 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.

    ## Building the API standard into an Optometry PMS
    
    Use the following steps to implement the API 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. 

    ## Onboarding
    
    Liaise with NHSX for onboarding your service into live operation.
    

servers:
  # Added by API Auto Mocking Plugin

  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/Sphinx/Eyecare/1.0
  - url: 'http://localhost:3000'
paths:
  '/referrals':
    post:
      summary: 'POST Referrals'
      operationId: post-referrals
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              example:
                example-1:
                  value:
                    referralID: 123e4567-e89b-12d3-a456-426614174000
                    referralURL: >-
                      https://someEeRSSystem/referrals/123e4567-e89b-12d3-a456-426614174000
                    referralStatus: incomplete
                    errorMessage: ''
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              example:
                Bad request response:
                  value:
                    referralID: ''
                    referralURL: ''
                    errorMessage: The request was malformed and couldn't be processed
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable Entity (WebDAV)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              example:
                Unprocessable example (business rule failures etc.):
                  value:
                    referralID: ''
                    referralURL: ''
                    errorMessage: >-
                      The request was syntactically correct but couldn't be
                      processed
        '500':
          description: Internal Server Error
      description: >-
        ### Create a new referral in the EeRS system
        Step 1: Clinician decides to launch a referral and clicks “refer via EeRS” or similar on the PMS system
          - PMS system gathers the data payload to send via the API
          - PMS system identifies the EeRS supplier API to call based on the optom practice where the practitioner has clicked ‘launch EeRS referral’
          - PMS system initiates API by sending API key to the digital referrals (EeRS) supplier in question with the data payload
          - Digital referrals supplier provides a response 201 with a URL - or an error message
          - PMS system launches the URL for the user
        Step 2: The user can now see the data rendered in the digital referrals system on their browser, and can complete the referral
        Step 3: The user sends and/or saves the referral using the digital referrals system.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Referral'
            example: {}
  '/referral/{referralID}/status':
    parameters:
      - schema:
          type: string
        name: referralID
        description: referral ID
        in: path
        required: true
    get:
      summary: GET referral status
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                example-1:
                  value:
                    referralStatus: incomplete
        '401':
          description: Unauthorized
        '404':
          description: Referral with given ID not found
        '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.
          - PMS system requests a status check to a specific referral ID using the same API key as for the referral
          - EeRS supplier provides response
          - PMS system exposes the URL associated with the referral from the original API call associated with that referral, so that the user can receive a prompt to complete their referral in the EeRS system without additional manual authentication.
components:
  schemas:
    Referral:
      title: Referral
      type: object
      example:
        - urgent: emergencyASAP
          dateOfSightTest: '2019-08-24'
          dateOfReferral: '2019-08-24'
          patient:
            NHSNumber: '1234567890'
            name:
              prefix: Mrs
              given: Jane
              family: Jones
              fullName: ''
            gender: female
            address:
              line:
                - 1 The Road
                - Wetherby
                - North Yorkshire
              postcode: LS10 1JR
            telephone: 01937 123456
            mobile: 07545 123456
            email: j.jones@nowhere.com
            dateOfBirth: '1997-08-11'
          reasonForReferral: string
          guardian:
            name:
              prefix: Mr
              given: Harry
              family: Jones
              fullName: ''
            address:
              line:
                - 1 Station Road
                - Leeds
              postcode: LS15 8DT
          referrer:
            GOCNumber: string
            name:
              text: Gosia Daria
            practice:
              ODSCode: G7H8J
              name: The Eyecare Practice
              address:
                line:
                  - Floor 2
                  - Poppleton Court
                  - George Street
                  - Wakefield
                postcode: WF1 1AA
              email: gdaria@theeyecarepracticewakefield.co.uk
              telephone: 01924 567890
          GP:
            name:
              prefix: Mr
              given: Harry
              family: Jones
              fullName: ''
            practice:
              ODSCode: G7A9I
              name: The Practice
              address:
                line:
                  - 1 Station Road
                  - Leeds
                postcode: LS15 8DT
              email: reception@theleedsexamplepractice.nhs.uk
              telephone: 0113 212 3456
          GPAction: informationOnly
          referTo:
            adultClinic: cataract
          clinicalTerms:
            - string
          refraction:
            left:
              sphere: -2
              cylinder: 0.75
              axis: 70
              nearPrism:
                in: 1
              distancePrism:
                in: 1.25
                down: 0.75
              VA: 6/5
              pinhole: 6/6
              add: 1.75
              nearVision: n5
              previousCorrectedVA: 6/9-3
              previousCorrectedVADate: '2019-08-24'
              unaidedVision: 6/18-2
            right:
              sphere: -2
              cylinder: 0.75
              axis: 70
              nearPrism:
                in: 1
              distancePrism:
                in: 1.25
                down: 0.75
              VA: 6/5
              pinhole: 6/6
              add: 1.75
              nearVision: n5
              previousCorrectedVA: 6/9-3
              previousCorrectedVADate: '2019-08-24'
              unaidedVision: 6/18-2
          additionalClinicalFindings:
            intraocularPressureTime: '14:15:22Z'
            tonometerUsed: string
            fieldsInstrumentUsed: string
            left:
              visualField: normal
              cdRatio: 0.3
              opticDiscAppearance: Pink and healthy
              averageIntraocularPressure: '12'
            right:
              visualField: normal
              cdRatio: 0.3
              opticDiscAppearance: Pink and healthy
              averageIntraocularPressure: '12'
          cycloplegicRefraction: true
          dilatedFundusExamination: true
          additionalInformation: string
          pmsWebhookCallback: 'http://example.com'
      description: ''
      properties:
        urgent:
          type: string
          enum:
            - notUrgent
            - urgent
            - emergencyASAP
            - emergency24Hours
        dateOfSightTest:
          $ref: '#/components/schemas/Date'
        dateOfReferral:
          $ref: '#/components/schemas/Date'
        reasonForReferral:
          type: string
        patient:
          $ref: '#/components/schemas/Patient'
        guardian:
          type: object
          properties:
            name:
              $ref: '#/components/schemas/Name'
            address:
              $ref: '#/components/schemas/Address'
        referrer:
          $ref: '#/components/schemas/Referrer'
        GP:
          type: object
          properties:
            name:
              $ref: '#/components/schemas/Name'
            practice:
              $ref: '#/components/schemas/Practice'
        GPAction:
          type: string
          enum:
            - informationOnly
            - adviseReferralToEyeDept
            - patientSentToCasualty
            - patientAskedToTelephoneOrVisitGP
        referTo:
          oneOf:
            - properties:
                adultClinic:
                  type: string
                  enum:
                    - cataract
                    - cornea
                    - diabeticMedicalRetina
                    - externalEyeDisease
                    - glaucoma
                    - laserYAG
                    - lowVision
                    - oculoplasticsOrbitsLacrimal
                    - otherMedicalRetina
                    - squintOcularMotility
                    - vitreolineal
                    - notOtherwiseSpecified
            - properties:
                childClinic:
                  type: string
                  enum:
                    - strabismus
                    - amblyopia
                    - paediatricNonStrabismus
                    - orthopticOnly
          type: object
        clinicalTerms:
          type: array
          items:
            type: string
        refraction:
          $ref: '#/components/schemas/Refraction'
        additionalClinicalFindings:
          type: object
          properties:
            intraocularPressureTime:
              type: string
              format: time
              description: >-
                The time of the intraocular pressure reading in ISO 8601
                compliant format
            tonometerUsed:
              type: string
            fieldsInstrumentUsed:
              type: string
            right:
              $ref: '#/components/schemas/AdditionalClinicalFindings'
            left:
              $ref: '#/components/schemas/AdditionalClinicalFindings'
        cycloplegicRefraction:
          type: boolean
        dilatedFundusExamination:
          type: boolean
        additionalInformation:
          type: string
        pmsWebhookCallback:
          type: string
          description: Placeholder for future callback API
          format: uri
    Patient:
      title: Patient
      type: object
      example:
        - NHSNumber: '1234567890'
          name:
            prefix: Mrs
            given: Jane
            family: Jones
            fullName: ''
          gender: female
          address:
            line:
              - 1 The Road
              - Wetherby
              - North Yorkshire
            postcode: LS10 1JR
          telephone: 01937 123456
          mobile: 07545 123456
          email: j.jones@nowhere.com
          dateOfBirth: '1997-08-11'
      description: ''
      properties:
        NHSNumber:
          type: string
        name:
          $ref: '#/components/schemas/Name'
        gender:
          type: string
          enum:
            - indeterminate
            - female
            - male
          description: >-
            Enum values from NHS Data Dictionary PERSON PHENOTYPIC SEX
            CLASSIFICATION
            (https://datadictionary.nhs.uk/attributes/person_phenotypic_sex_classification.html)
        address:
          $ref: '#/components/schemas/Address'
        telephone:
          type: string
        mobile:
          type: string
        email:
          type: string
        dateOfBirth:
          $ref: '#/components/schemas/Date'
    Address:
      title: Address
      type: object
      description: ''
      properties:
        line:
          type: array
          items:
            type: string
        postcode:
          type: string
      example:
        - line:
            - 1 Station Road
            - Leeds
          postcode: LS15 8DT
    Date:
      type: string
      title: Date
      example:
        - '2019-08-24'
      description: A date in ISO 8601 compliant format
      format: date
    Name:
      title: Name
      type: object
      example:
        - prefix: Mr
          given: Harry
          family: Jones
          fullName: ''
        - prefix: Dr
          given: F
          family: Jones
          fullName: Dr F Jones
        - prefix: ''
          given: ''
          family: ''
          fullName: Jane Jones
      description: >-
        Represents a person's name. Provides the option to include the name
        broken down if held.
      properties:
        prefix:
          type: string
        given:
          type: string
        family:
          type: string
        fullName:
          type: string
          description: Text representation of the full name
    Referrer:
      title: Referrer
      type: object
      example:
        - GOCNumber: string
          name:
            fullName: Gosia Daria
          practice:
            ODSCode: G7H8J
            name: The Eyecare Practice
            address:
              line:
                - Floor 2
                - Poppleton Court
                - George Street
                - Wakefield
              postcode: WF1 1AA
            email: gdaria@theeyecarepracticewakefield.co.uk
            telephone: 01924 567890
      properties:
        GOCNumber:
          type: string
        name:
          $ref: '#/components/schemas/Name'
        practice:
          $ref: '#/components/schemas/Practice'
    Practice:
      title: Practice
      type: object
      properties:
        ODSCode:
          type: string
        name:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        email:
          type: string
        telephone:
          type: string
      example:
        - ODSCode: G7A9I
          name: The Practice
          address:
            line:
              - 1 Station Road
              - Leeds
            postcode: LS15 8DT
          email: reception@theleedsexamplepractice.nhs.uk
          telephone: 0113 212 3456
    Refraction:
      title: VisionTest
      type: object
      example:
        - sphere: -2
          cylinder: 0.75
          axis: 70
          nearPrism:
            in: 1
          distancePrism:
            in: 1.25
            down: 0.75
          VA: 6/5
          pinhole: 6/6
          add: 1.75
          nearVision: n5
          previousCorrectedVA: 6/9-3
          previousCorrectedVADate: '2019-08-24'
          unaidedVision: 6/18-2
      properties:
        sphere:
          type: number
        cylinder:
          type: number
        axis:
          type: number
        nearPrism:
          $ref: '#/components/schemas/Prism'
        distancePrism:
          $ref: '#/components/schemas/Prism'
        VA:
          type: string
        VAMeasure:
          type: string
          description: 'E.g. Snellen, Logmar'
        pinhole:
          type: string
        add:
          type: number
        nearVision:
          type: string
        previousCorrectedVA:
          type: string
        previousCorrectedVADate:
          $ref: '#/components/schemas/Date'
        unaidedVision:
          type: string
    AdditionalClinicalFindings:
      title: AdditionalClinicalFindings
      type: object
      example:
        - visualField: normal
          cdRatio: 0.3
          opticDiscAppearance: Pink and healthy
          averageIntraocularPressure: '12'
      properties:
        visualField:
          type: string
        cdRatio:
          type: number
          description: 'C:D'
        opticDiscAppearance:
          type: string
        averageIntraocularPressure:
          type: number
        intraocularPressureReadings:
          type: array
          items:
            type: number
      description: ''
    Response:
      title: Response
      type: object
      properties:
        referralID:
          type: string
          description: >-
            The unique, system-agnostic identifier of the referral. Must be an
            RCF 4122 compliant UUID
        referralURL:
          type: string
          description: >-
            The EeRS URL the user should be redirected to for viewing the
            created referral. Only returned for a response of 201 CREATED
        referralStatus:
          type: string
        errorMessage:
          type: string
          description: >-
            For responses other than 201 CREATED an error message will be
            populated
      example:
        - referralID: string
          referralURL: string
          referralStatus: string
          errorMessage: string
        - referralID: string
          referralURL: string
          referralStatus: string
          errorMessage: string
    StatusResponse:
      title: StatusResponse
      type: object
      properties:
        referralStatus:
          type: string
          enum:
            - incomplete
            - submitted
            - closednotsubmitted
      description: >-
        Shows the current status of the referral which will be one of:
        * incomplete - the referral has been received in the EeRS system but has
        not yet not been closed or submitted
        * submitted - the referral has been submitted to a provider of onwards care
        * closednotsubmitted - the referral has been closed by the user without being submitted for any further review or action by service providers
        e.g. because a clinician decided that a referral wasn't necessary
      example:
        - referralStatus: incomplete
        - referralStatus: submitted
        - referralStatus: closednotsubmitted
    Prism:
      title: Prism
      oneOf:
        - type: string
          description: >-
            Allows the base and prism to be represented as an unformatted string
            as entered by the user
        - type: object
          properties:
            in:
              type: number
            out:
              type: number
            up:
              type: number
            down:
              type: number
          minProperties: 1
      example:
        - in: 0.5
          down: 1
        - '1/2 BU, 1 BI'
  securitySchemes:
    apikey:
      name: API key to identify calling client
      type: apiKey
      in: header
  responses: {}
security:
  - apikey: []