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

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

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

    ### Optom PMS sender guidance

    Use JSON NULL to represent an empty field you wish to include instead of emptry string.

    ### EeRS provider guidance

    Any non-mandatory field will either be included as JSON null or not inlcuded at all from the sending Optom PMS system. When saving a new referral initialise these fields to null.
    
    ## 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.
    
    ### Version control

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

    In general, once an API is stable (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 a stable 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.
    
    ## 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 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 [here](https://www.nhsx.nhs.uk/contact-us/).

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: 'POST referrals'
      operationId: post-referrals  
      parameters: 
        - $ref: '#/components/parameters/VersionHeader'
      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: ''
                    errorCode: ''
          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]. | E0002     | No JSON was received in the request body. | 
            | 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               |
            | 422         | GOC Number Invalid                                         | E0007         | The value supplied in the GOCNumber field is not valid as defined by the EeRS                      |
            | 422         | A data type could not be converted                         | E0008         | This error is used when the conversion to the target data type cannot be made.                      |
      
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              example:
                Bad request response:
                  value:
                    referralID: ''
                    referralURL: ''
                    referralStatus: ''
                    errorMessage: As per description
                    errorCode: As per description
          headers:
            Accept-Version:
              description: The Version number of the API you wish to call.
              schema:
                type: string
        '500':
          description: Internal Server Error
          headers:
            Accept-Version:
              description: The Version number of the API you wish to call.
              schema:
                type: string
      description: >-
         
         ### 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 PMS system
          **Step 2**: PMS system gathers the data payload to send via the API
          **Step 3**: PMS system identifies the EeRS supplier API to call based on the optom practice where the practitioner has clicked ‘create EeRS referral’
          **Step 4**: PMS system 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**: PMS system launches the URL for the user in a browser
          **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 EeRS.

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Referral'
  '/referral/{referralID}/status':
    parameters:
      - schema:
          type: string
        name: referralID
        description: referral ID
        in: path
        required: true
    get:
      summary: GET referral status
      parameters: 
        - $ref: '#/components/parameters/VersionHeader'
      tags: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                example-1:
                  value:
                    referralStatus: incomplete
          headers:
            Accept-Version:
              description: The Version number of the API you invoked.
              schema:
                type: string
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              example:
                Bad request response:
                  value:
                    referralStatus: ''
                    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/Response'
              example:
                Bad request response:
                  value:
                    referralStatus: ''
                    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/Response'
              example:
                Bad request response:
                  value:
                    referralStatus: ''
                    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        
          headers:
            Accept-Version:
              description: The Version number of the API you invoked.
              schema:
                type: string

      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: Authorisation
  parameters:
    VersionHeader:
      name: Accept-Version
      description:  The Version number of the API you invoked.
      in: header
      schema:
        type: string
        example: 1.0.0
  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: Needs assessment for cataract surgery
          guardian:
            name:
              prefix: Mr
              given: Harry
              family: Jones
              fullName: ''
            address:
              line:
                - 1 Station Road
                - Leeds
              postcode: LS15 8DT
          referrer:
            registrantType: GOCRegistrant
            registrantNumber: 01-12345
            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: [cataract]
          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: Patient has accessibility needs
          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
      required:  # List the required properties here
        - registrantType
        - registrantNumber
      example:
          registrantType: GOCRegistrant
          registrantNumber: 01-12345
          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:

        registrantType:
          type: string 
          default: GOCRegistrant
          enum:
            - GOCRegistrant
            - GMCRegistrant
        registrantNumber:
          type: string
        name:
          $ref: '#/components/schemas/Name'
        practice:
          $ref: '#/components/schemas/Practice'
    Practice:
      title: Practice
      type: object
      required:  # List the required properties here
        - ODSCode 
      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
        errorCode:
          type: string
          description: >-
            For responses other than 201 CREATED an error code will be
            populated    
      example:
        - referralID: string
          referralURL: string
          referralStatus: string
          errorMessage: string
          errorCode: string
        - referralID: string
          referralURL: string
          referralStatus: string
          errorMessage: string
          errorCode: 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'
  responses: {}