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

- ReferralYaml — unresolved $ref

## Response `201`

Created

- ResponseYaml — unresolved $ref

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

## Changes

- **2022-02-16** `943937150819` — 2 breaking, 10 warning
  - the response's body type/format changed from `object`/`` to ``/`` for status `201`
  - the response's body type/format changed from `object`/`` to ``/`` for status `4XX`
  - removed the optional property `errorCode` from the response with the `201` status
  - removed the optional property `errorCode` from the response with the `4XX` status
  - …8 more
- **2022-02-15** `33f872ef2577` — 1 breaking, 17 warning
  - the request's body type/format changed from `object`/`` to ``/``
  - removed the request property `GP`
  - removed the request property `GPAction`
  - removed the request property `additionalClinicalFindings`
  - …14 more
- **2022-01-12** `4d66bed492b9` — 1 warning
  - the optional response header `Accept-Version` removed for the status `500`
- **2022-01-11** `585b6106a0a5` — 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - added the new optional `header` request parameter `api-key`
- **2022-01-11** `9033330ddb63` — 1 info
  - added the new optional `header` request parameter `Authorization`

[Full history](https://skmtc.dev/nhs/apis/eyecare-electronic-referral-api/changes/referrals/post.md)

---

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