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).
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:
- Identify the data fields in your system that correspond to the data fields in the specification.
- Ask the EeRS supplier to provide their API endpoint.
- Ask the EeRS supplier you are integrating with to provide a system-to-system API key.
- Develop your system to connect to the API and send the API key with the data payload to that EeRS endpoint.
- 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
- 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.
Status and roadmap
This API standard is in draft.
To suggest, comment or vote on features for this API, see our interactive product backlog.
If you have any other queries, 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 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.
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.
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 for more on errors.
Endpoints
Create a referral
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.
Request
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you wish to call.
Example: 1.0.0
|
api-key |
String
The API Key associated with the calling API consumer.
Example: KdsASD78FA5Sjl342kfwreas
|
Body
Content type: application/json
Example
{
"urgent" : "emergencyASAP",
"dateOfSightTest" : "2019-08-24",
"dateOfReferral" : "2019-08-24",
"patient" : {
"NHSNumber" : "1234567890",
"name" : {
"prefix" : "Mrs",
"given" : "Jane",
"family" : "Jones",
"fullName" : null
},
"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" : null
},
"address" : {
"line" : [ "1 Station Road", "Leeds" ],
"postcode" : "LS15 8DT"
}
},
"referrer" : {
"registrantType" : "GOCRegistrant",
"registrantNumber" : "01-12345",
"name" : {
"prefix" : null,
"given" : "Gosia",
"family" : "Daria",
"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"
}
},
"GP" : {
"name" : {
"prefix" : "Mr",
"given" : "Harry",
"family" : "Jones",
"fullName" : null
},
"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"
}
|
object
|
Referral
The referral to be created |
|
urgent
string
|
Allowed values: notUrgent, urgent, emergencyASAP, emergency24Hours
|
|
dateOfSightTest
string
date
|
A date in ISO 8601 compliant format Example: 2019-08-24
|
|
dateOfReferral
string
date
|
A date in ISO 8601 compliant format Example: 2019-08-24
|
|
reasonForReferral
string
|
Example: Needs assessment for cataract surgery
|
|
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. Example: 9000000009
|
|
name
object
|
Represents a person's name. Provides the option to include the name broken down if held. |
|
prefix
string
|
Example: Mrs
|
|
given
string
|
Example: Jane
|
|
family
string
|
Example: Jones
|
|
fullName
string
|
Text representation of the full name |
|
gender
string
|
Enum values from NHS Data Dictionary PERSON PHENOTYPIC SEX CLASSIFICATION (https://datadictionary.nhs.uk/attributes/person_phenotypic_sex_classification.html) Allowed values: indeterminate, female, male
|
|
address
object
|
|
|
line
array
|
Example: ["1 The Road","Wetherby","North Yorkshire"]
|
|
string
|
|
|
postcode
string
|
Example: LS10 1JR
|
|
telephone
string
|
Example: 01937 123456
|
|
mobile
string
|
Example: 07545 123456
|
|
email
string
|
Example: j.jones@nowhere.com
|
|
dateOfBirth
string
date
|
A date in ISO 8601 compliant format Example: 2019-08-24
|
|
guardian
object
|
|
|
name
object
|
Represents a person's name. Provides the option to include the name broken down if held. |
|
prefix
string
|
Example: Mrs
|
|
given
string
|
Example: Jane
|
|
family
string
|
Example: Jones
|
|
fullName
string
|
Text representation of the full name |
|
address
object
|
|
|
line
array
|
Example: ["1 The Road","Wetherby","North Yorkshire"]
|
|
string
|
|
|
postcode
string
|
Example: LS10 1JR
|
|
referrer
object
|
Referrer
|
|
registrantType
string
required
|
Allowed values: GOCRegistrant, GMCRegistrant
Default: GOCRegistrant
|
|
registrantNumber
string
required
|
Example: 01-12345
|
|
name
object
|
Represents a person's name. Provides the option to include the name broken down if held. |
|
prefix
string
|
Example: Mrs
|
|
given
string
|
Example: Jane
|
|
family
string
|
Example: Jones
|
|
fullName
string
|
Text representation of the full name |
|
practice
object
|
Practice
|
|
ODSCode
string
required
|
Example: G7H8J
|
|
name
string
|
Example: The Eyecare Practice
|
|
address
object
|
|
|
line
array
|
Example: ["1 The Road","Wetherby","North Yorkshire"]
|
|
string
|
|
|
postcode
string
|
Example: LS10 1JR
|
|
email
string
|
Example: gdaria@theeyecarepracticewakefield.co.uk
|
|
telephone
string
|
Example: 01924 567890
|
|
GP
object
|
|
|
name
object
|
Represents a person's name. Provides the option to include the name broken down if held. |
|
prefix
string
|
Example: Mrs
|
|
given
string
|
Example: Jane
|
|
family
string
|
Example: Jones
|
|
fullName
string
|
Text representation of the full name |
|
practice
object
|
Practice
|
|
ODSCode
string
required
|
Example: G7H8J
|
|
name
string
|
Example: The Eyecare Practice
|
|
address
object
|
|
|
line
array
|
Example: ["1 The Road","Wetherby","North Yorkshire"]
|
|
string
|
|
|
postcode
string
|
Example: LS10 1JR
|
|
email
string
|
Example: gdaria@theeyecarepracticewakefield.co.uk
|
|
telephone
string
|
Example: 01924 567890
|
|
GPAction
string
|
Allowed values: informationOnly, adviseReferralToEyeDept, patientSentToCasualty, patientAskedToTelephoneOrVisitGP
|
|
referTo
object
|
|
|
oneOf
|
|
|
|
|
|
adultClinic
string
|
Allowed values: cataract, cornea, diabeticMedicalRetina, externalEyeDisease, glaucoma, laserYAG, lowVision, oculoplasticsOrbitsLacrimal, otherMedicalRetina, squintOcularMotility, vitreolineal, notOtherwiseSpecified
|
|
|
|
|
childClinic
string
|
Allowed values: strabismus, amblyopia, paediatricNonStrabismus, orthopticOnly
|
|
refraction
object
|
VisionTest
|
|
sphere
number
|
Example: -2
|
|
cylinder
number
|
Example: 0.75
|
|
axis
number
|
Example: 70
|
|
nearPrism
|
Prism
|
|
oneOf
|
|
|
string
|
Allows the base and prism to be represented as an unformatted string as entered by the user. |
|
object
|
Min properties: 1
|
|
in
number
|
Example: 1.25
|
|
out
number
|
|
|
up
number
|
|
|
down
number
|
Example: 0.75
|
|
distancePrism
|
Prism
|
|
oneOf
|
|
|
string
|
Allows the base and prism to be represented as an unformatted string as entered by the user. |
|
object
|
Min properties: 1
|
|
in
number
|
Example: 1.25
|
|
out
number
|
|
|
up
number
|
|
|
down
number
|
Example: 0.75
|
|
VA
string
|
Example: 6/5
|
|
VAMeasure
string
|
|
|
pinhole
string
|
Example: 6/6
|
|
add
number
|
Example: 1.75
|
|
nearVision
string
|
Example: n5
|
|
previousCorrectedVA
string
|
Example: 6/9-3
|
|
previousCorrectedVADate
string
date
|
A date in ISO 8601 compliant format Example: 2019-08-24
|
|
unaidedVision
string
|
Example: 6/18-2
|
|
additionalClinicalFindings
object
|
|
|
intraocularPressureTime
string
time
|
The time of the intraocular pressure reading in ISO 8601 compliant format Example: 14:15:22Z
|
|
tonometerUsed
string
|
|
|
fieldsInstrumentUsed
string
|
|
|
right
object
|
AdditionalClinicalFindings
|
|
visualField
string
|
Example: normal
|
|
cdRatio
number
|
Example: 0.3
|
|
opticDiscAppearance
string
|
Example: Pink and healthy
|
|
averageIntraocularPressure
number
|
Example: 12
|
|
intraocularPressureReadings
array
|
|
|
number
|
|
|
left
object
|
AdditionalClinicalFindings
|
|
visualField
string
|
Example: normal
|
|
cdRatio
number
|
Example: 0.3
|
|
opticDiscAppearance
string
|
Example: Pink and healthy
|
|
averageIntraocularPressure
number
|
Example: 12
|
|
intraocularPressureReadings
array
|
|
|
number
|
|
|
cycloplegicRefraction
boolean
|
|
|
dilatedFundusExamination
boolean
|
|
|
additionalInformation
string
|
Example: Patient has accessibility needs
|
|
pmsWebhookCallback
string
uri
|
Placeholder for callback API Example: http://example.com
|
Response
HTTP status: 201
Created
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you wish to call.
Example: 1.0.0
|
Body
Content type: application/json
Example
{
"referralID" : "123e4567-e89b-12d3-a456-426614174000",
"referralURL" : "https://someEeRSSystem/referrals/123e4567-e89b-12d3-a456-426614174000",
"referralStatus" : "incomplete"
}
|
object
|
Response
|
|
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 |
HTTP status: 500
Internal Server Error
HTTP status: 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. |
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you wish to call.
|
Body
Content type: application/json
Example
{
"errorMessage" : "Malformed JSON",
"errorCode" : "E0001"
}
|
object
|
Response
|
|
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 |
Get referral status
get
/referral/{referralID}/status
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
Request
Path parameters
| Name |
Description |
referralID |
String
The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID.
Example: 123e4567-e89b-12d3-a456-426614174000
Required
|
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you wish to call.
Example: 1.0.0
|
api-key |
String
The API Key associated with the calling API consumer.
Example: KdsASD78FA5Sjl342kfwreas
|
Response
HTTP status: 200
OK
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you wish to invoke.
Example: 1.0.0
|
Body
Content type: application/json
Example
{
"referralStatus" : "incomplete"
}
|
object
|
StatusResponse
|
|
referralStatus
string
|
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 for onward 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.
- printed - the referral was entered manually.
Only populated for 200 SUCCESS response.
Allowed values: incomplete, submitted, closednotsubmitted, printed
|
|
errorMessage
string
|
For responses other than 200 SUCCESS an error message will be populated. |
|
errorCode
string
|
For responses other than 200 SUCCESS an error code will be populated. |
HTTP status: 400
Bad Request
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you invoked.
|
Body
Content type: application/json
Example
{
"errorMessage" : "The request was malformed and couldn't be processed",
"errorCode" : "E0001"
}
|
object
|
StatusResponse
|
|
referralStatus
string
|
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 for onward 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.
- printed - the referral was entered manually.
Only populated for 200 SUCCESS response.
Allowed values: incomplete, submitted, closednotsubmitted, printed
|
|
errorMessage
string
|
For responses other than 200 SUCCESS an error message will be populated. |
|
errorCode
string
|
For responses other than 200 SUCCESS an error code will be populated. |
HTTP status: 401
Unauthorized
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you invoked.
|
Body
Content type: application/json
Example
{
"errorMessage" : "The API-KEY is invalid",
"errorCode" : "E0010"
}
|
object
|
StatusResponse
|
|
referralStatus
string
|
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 for onward 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.
- printed - the referral was entered manually.
Only populated for 200 SUCCESS response.
Allowed values: incomplete, submitted, closednotsubmitted, printed
|
|
errorMessage
string
|
For responses other than 200 SUCCESS an error message will be populated. |
|
errorCode
string
|
For responses other than 200 SUCCESS an error code will be populated. |
HTTP status: 404
Referral with given ID not found
Headers
| Name |
Description |
Accept-Version |
String
The version number of the API you invoked.
|
Body
Content type: application/json
Example
{
"errorMessage" : "ReferralID cannot be found by the receiving system",
"errorCode" : "E0005"
}
|
object
|
StatusResponse
|
|
referralStatus
string
|
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 for onward 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.
- printed - the referral was entered manually.
Only populated for 200 SUCCESS response.
Allowed values: incomplete, submitted, closednotsubmitted, printed
|
|
errorMessage
string
|
For responses other than 200 SUCCESS an error message will be populated. |
|
errorCode
string
|
For responses other than 200 SUCCESS an error code will be populated. |
HTTP status: 500
Internal Server Error
