Skip to main content

Eyecare Electronic Referral Service API standard

Pass details of a new referral to an Eyecare Electronic Referral System (EeRS).

Page content

Overview

Use this API standard to pass details of a new 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:

  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.

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:

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

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.

API status and roadmap

This API standard is in beta, 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.

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.

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.

Endpoints

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

referral ID

Required
Headers
Name Description
Accept-Version

String

The version number of the API you invoked.

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

Content type: application/json

Example

Schema

Name Description
object
StatusResponse

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.
  • printed - the referral was entered manually.
Example: 
[ {
  "referralStatus" : "incomplete"
}, {
  "referralStatus" : "submitted"
}, {
  "referralStatus" : "closednotsubmitted"
}, {
  "referralStatus" : "printed"
} ]
referralStatus
string
Allowed values: incomplete, submitted, closednotsubmitted, printed
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

Schema

Name Description
object
Response
Example: 
[ {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
}, {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
} ]
referralID
string

The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID
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
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: 401

Unauthorized

Headers
Name Description
Accept-Version

String

The Version number of the API you invoked.
Body

Content type: application/json

Example

Schema

Name Description
object
Response
Example: 
[ {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
}, {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
} ]
referralID
string

The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID
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
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: 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

Schema

Name Description
object
Response
Example: 
[ {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
}, {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
} ]
referralID
string

The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID
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
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

POST referrals

post 
/referrals

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.

Request

Headers
Name Description
Accept-Version

String

The version number of the API you invoked.

Example: 1.0.0

api-key

String

The API Key associated with the calling API consumer.

Example: KdsASD78FA5Sjl342kfwreas

Body

Content type: application/json

Example

Schema

Name Description
object
Referral
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"
} ]
urgent
string
Allowed values: notUrgent, urgent, emergencyASAP, emergency24Hours
dateOfSightTest
string date
Date

A date in ISO 8601 compliant format
dateOfReferral
string date
Date

A date in ISO 8601 compliant format
reasonForReferral
string
patient
object
Patient
Example: 
[ {
  "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"
} ]
NHSNumber
string
name
object
Name

Represents a person's name. Provides the option to include the name broken down if held.

Example: 
[ {
  "prefix" : "Mr",
  "given" : "Harry",
  "family" : "Jones",
  "fullName" : null
}, {
  "prefix" : "Dr",
  "given" : "F",
  "family" : "Jones",
  "fullName" : "Dr F Jones"
}, {
  "prefix" : null,
  "given" : null,
  "family" : null,
  "fullName" : "Jane Jones"
} ]
prefix
string
given
string
family
string
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
Address
Example: 
[ {
  "line" : [ "1 Station Road", "Leeds" ],
  "postcode" : "LS15 8DT"
} ]
line
array
string
postcode
string
telephone
string
mobile
string
email
string
dateOfBirth
string date
Date

A date in ISO 8601 compliant format
guardian
object
name
object
Name

Represents a person's name. Provides the option to include the name broken down if held.

Example: 
[ {
  "prefix" : "Mr",
  "given" : "Harry",
  "family" : "Jones",
  "fullName" : null
}, {
  "prefix" : "Dr",
  "given" : "F",
  "family" : "Jones",
  "fullName" : "Dr F Jones"
}, {
  "prefix" : null,
  "given" : null,
  "family" : null,
  "fullName" : "Jane Jones"
} ]
prefix
string
given
string
family
string
fullName
string

Text representation of the full name
address
object
Address
Example: 
[ {
  "line" : [ "1 Station Road", "Leeds" ],
  "postcode" : "LS15 8DT"
} ]
line
array
string
postcode
string
referrer
object
Referrer
Example: 
{
  "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"
  }
}
registrantType
string
required
Allowed values: GOCRegistrant, GMCRegistrant
Default: GOCRegistrant
registrantNumber
string
required
name
object
Name

Represents a person's name. Provides the option to include the name broken down if held.

Example: 
[ {
  "prefix" : "Mr",
  "given" : "Harry",
  "family" : "Jones",
  "fullName" : null
}, {
  "prefix" : "Dr",
  "given" : "F",
  "family" : "Jones",
  "fullName" : "Dr F Jones"
}, {
  "prefix" : null,
  "given" : null,
  "family" : null,
  "fullName" : "Jane Jones"
} ]
prefix
string
given
string
family
string
fullName
string

Text representation of the full name
practice
object
Practice
Example: 
[ {
  "ODSCode" : "G7A9I",
  "name" : "The Practice",
  "address" : {
    "line" : [ "1 Station Road", "Leeds" ],
    "postcode" : "LS15 8DT"
  },
  "email" : "reception@theleedsexamplepractice.nhs.uk",
  "telephone" : "0113 212 3456"
} ]
ODSCode
string
required
name
string
address
object
Address
Example: 
[ {
  "line" : [ "1 Station Road", "Leeds" ],
  "postcode" : "LS15 8DT"
} ]
line
array
string
postcode
string
email
string
telephone
string
GP
object
name
object
Name

Represents a person's name. Provides the option to include the name broken down if held.

Example: 
[ {
  "prefix" : "Mr",
  "given" : "Harry",
  "family" : "Jones",
  "fullName" : null
}, {
  "prefix" : "Dr",
  "given" : "F",
  "family" : "Jones",
  "fullName" : "Dr F Jones"
}, {
  "prefix" : null,
  "given" : null,
  "family" : null,
  "fullName" : "Jane Jones"
} ]
prefix
string
given
string
family
string
fullName
string

Text representation of the full name
practice
object
Practice
Example: 
[ {
  "ODSCode" : "G7A9I",
  "name" : "The Practice",
  "address" : {
    "line" : [ "1 Station Road", "Leeds" ],
    "postcode" : "LS15 8DT"
  },
  "email" : "reception@theleedsexamplepractice.nhs.uk",
  "telephone" : "0113 212 3456"
} ]
ODSCode
string
required
name
string
address
object
Address
Example: 
[ {
  "line" : [ "1 Station Road", "Leeds" ],
  "postcode" : "LS15 8DT"
} ]
line
array
string
postcode
string
email
string
telephone
string
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
clinicalTerms
array
string
refraction
object
VisionTest
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"
} ]
sphere
number
cylinder
number
axis
number
nearPrism
Prism
Example: 
[ {
  "in" : 0.5,
  "down" : 1
}, "1/2 BU, 1 BI" ]
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
out
number
up
number
down
number
distancePrism
Prism
Example: 
[ {
  "in" : 0.5,
  "down" : 1
}, "1/2 BU, 1 BI" ]
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
out
number
up
number
down
number
VA
string
VAMeasure
string

E.g. Snellen, Logmar
pinhole
string
add
number
nearVision
string
previousCorrectedVA
string
previousCorrectedVADate
string date
Date

A date in ISO 8601 compliant format
unaidedVision
string
additionalClinicalFindings
object
intraocularPressureTime
string time

The time of the intraocular pressure reading in ISO 8601 compliant format
tonometerUsed
string
fieldsInstrumentUsed
string
right
object
AdditionalClinicalFindings
Example: 
[ {
  "visualField" : "normal",
  "cdRatio" : 0.3,
  "opticDiscAppearance" : "Pink and healthy",
  "averageIntraocularPressure" : "12"
} ]
visualField
string
cdRatio
number

C:D
opticDiscAppearance
string
averageIntraocularPressure
number
intraocularPressureReadings
array
number
left
object
AdditionalClinicalFindings
Example: 
[ {
  "visualField" : "normal",
  "cdRatio" : 0.3,
  "opticDiscAppearance" : "Pink and healthy",
  "averageIntraocularPressure" : "12"
} ]
visualField
string
cdRatio
number

C:D
opticDiscAppearance
string
averageIntraocularPressure
number
intraocularPressureReadings
array
number
cycloplegicRefraction
boolean
dilatedFundusExamination
boolean
additionalInformation
string
pmsWebhookCallback
string uri

Placeholder for callback API

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

Schema

Name Description
object
Response
Example: 
[ {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
}, {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
} ]
referralID
string

The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID
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
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

Schema

Name Description
object
Response
Example: 
[ {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
}, {
  "referralID" : "string",
  "referralURL" : "string",
  "referralStatus" : "string",
  "errorMessage" : "string",
  "errorCode" : "string"
} ]
referralID
string

The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID
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
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