---
title: "Create a referral"
method: POST
path: "/referrals"
---

# Create a referral

`POST /referrals`

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.

## Headers

- `Accept-Version` string
- `api-key` string

## Request body

- object — The referral to be created
  - `urgent` 'notUrgent' | 'urgent' | 'emergencyASAP' | 'emergency24Hours'
  - `dateOfSightTest` DateOfReferral — unresolved $ref
  - `dateOfReferral` string, date — A date in ISO 8601 compliant format
  - `reasonForReferral` string
  - `patient` object
    - `NHSNumber` string — 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.
    - `name` Name — unresolved $ref
    - `gender` 'indeterminate' | 'female' | 'male' — Enum values from NHS Data Dictionary PERSON PHENOTYPIC SEX CLASSIFICATION (https://datadictionary.nhs.uk/attributes/person_phenotypic_sex_classification.html)
    - `address` Address — unresolved $ref
    - `telephone` string
    - `mobile` string
    - `email` string
    - `dateOfBirth` DateOfReferral — unresolved $ref
  - `guardian` object
    - `name` Name — unresolved $ref
    - `address` object — Address details
      - `line` string[]
      - `postcode` string
  - `referrer` object
    - `registrantType` 'GOCRegistrant' | 'GMCRegistrant', required
    - `registrantNumber` string, required
    - `name` Name — unresolved $ref
    - `practice` Practice — unresolved $ref
  - `GP` object
    - `name` object — Represents a person's name. Provides the option to include the name broken down if held.
      - `prefix` string
      - `given` string
      - `family` string
      - `fullName` string — Text representation of the full name
    - `practice` object
      - `ODSCode` string, required
      - `name` string
      - `address` Address — unresolved $ref
      - `email` string
      - `telephone` string
  - `GPAction` 'informationOnly' | 'adviseReferralToEyeDept' | 'patientSentToCasualty' | 'patientAskedToTelephoneOrVisitGP'
  - `referTo` union
    - object
      - `adultClinic` 'cataract' | 'cornea' | 'diabeticMedicalRetina' | 'externalEyeDisease' | 'glaucoma' | 'laserYAG' | 'lowVision' | 'oculoplasticsOrbitsLacrimal' | 'otherMedicalRetina' | 'squintOcularMotility' | 'vitreolineal' | 'notOtherwiseSpecified'
    - object
      - `childClinic` 'strabismus' | 'amblyopia' | 'paediatricNonStrabismus' | 'orthopticOnly'
  - `refraction` object
    - `sphere` number
    - `cylinder` number
    - `axis` number
    - `nearPrism` union
      - string — Allows the base and prism to be represented as an unformatted string as entered by the user.
      - object
        - `in` number
        - `out` number
        - `up` number
        - `down` number
    - `distancePrism` NearPrism — unresolved $ref
    - `VA` string
    - `VAMeasure` string — E.g. Snellen, Logmar
    - `pinhole` string
    - `add` number
    - `nearVision` string
    - `previousCorrectedVA` string
    - `previousCorrectedVADate` DateOfReferral — unresolved $ref
    - `unaidedVision` string
  - `additionalClinicalFindings` object
    - `intraocularPressureTime` string, time — The time of the intraocular pressure reading in ISO 8601 compliant format
    - `tonometerUsed` string
    - `fieldsInstrumentUsed` string
    - `right` Left — unresolved $ref
    - `left` object
      - `visualField` string
      - `cdRatio` number — C:D
      - `opticDiscAppearance` string
      - `averageIntraocularPressure` number
      - `intraocularPressureReadings` number[]
  - `cycloplegicRefraction` boolean
  - `dilatedFundusExamination` boolean
  - `additionalInformation` string
  - `pmsWebhookCallback` string, uri — Placeholder for callback API

## Response `201`

Created

- object
  - `referralID` string — The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID. Only returned for a response of 201 CREATED
  - `referralURL` string — The EeRS URL the user should be redirected to for viewing the created referral. Only returned for a response of 201 CREATED
  - `referralStatus` string — The status of the referral in EeRS. Only returned for a response of 201 CREATED
  - `errorMessage` string — For responses other than 201 CREATED an error message will be populated
  - `errorCode` string — For responses other than 201 CREATED an error code will be populated

## Other responses

- `500` — Internal Server Error
- `4XX` — 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. |

---

[API](https://skmtc.dev/nhs/apis/eyecare-e-referral-service-api.md) · [All operations](https://skmtc.dev/nhs/apis/eyecare-e-referral-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nhs/eyecare-e-referral-service-api/revisions/e8db99493daa/schema)