{"openapi":"3.0.0","x-nhs-api-spec-guid":"bf6758a5-b731-4640-876a-f7ad56e36029","x-meta":{"service_name":"eyecare-electronic-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 eyecare referral to be passed to an Eyecare electroinc referral system (EeRS) from an Optometry patient management system.","pipeline_name_prefix":"Eyecare-Referrals"},"x-spec-publication":{"operation-order":[{"operations":[{"method":"POST","path":"/referrals"},{"method":"GET","path":"/referral/{referralID}/status"}]}]},"info":{"title":"Eyecare electronic Referral API","version":"1.0.0","contact":{"url":"https://digital.nhs.uk/developer/help-and-support","email":"api.management@nhs.net"},"description":"
\n
\n
\n
\n \n \"\"\n \n
\n
\n
\n
\n

This API standard is retired, meaning it is not being maintained and should not be used.

\n

Depending on your situation, you might be able to use the e-Referral Service FHIR API instead.

\n

If you have any other queries, contact us at england.eyecare-transformation@nhs.net.

\n
\n
\n
\n
\n\n## Overview\n\nUse 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).\n\nThe 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.\n\nEach 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/). \nEach EeRS system receives referrals using this API standard and provides its own endpoint for this service.\n\nThis 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. \n\n### Building the API standard into an Optometry PMS\n\nUse the following steps to implement the API standard as a sending Optometry PMS to a specific EeRS:\n\n1. Identify the data fields in your system that correspond to the data fields in the specification.\n2. Ask the EeRS supplier to provide their API endpoint.\n3. Ask the EeRS supplier you are integrating with to provide a system-to-system API key. \n4. Develop your system to connect to the API and send the API key with the data payload to that EeRS endpoint. \n5. 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\n6. 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. \n\n
\n
\n
\n \n \"\"\n \n
\n
\n

For a non-technical overview of how to build software that deals with referrals and bookings, see Building healthcare software - referrals and bookings.

\n
\n
\n\n## Who can use this API\n\nThis 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.\n\n## Status and roadmap\n\nThis API standard is [retired](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#statuses), meaning it is not being maintained and should not be used.\n\nDepending on your situation, you might be able to use the [e-Referral Service FHIR API](https://digital.nhs.uk/developer/api-catalogue/e-referral-service-fhir) instead.\n\nIf you have any other queries, contact us at [england.eyecare-transformation@nhs.net](mailto:england.eyecare-transformation@nhs.net).\n\n### Version control\n\nWe use HTTP headers to allow you to specify the API version you want to call.\n\nIn 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.\n\nIf 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.\n\nThis spec version: 1.0.0\n\n## Technology\n\nThis API standard uses RESTful technology, as described in our guidance [here](https://digital.nhs.uk/developer/guides-and-documentation/api-technologies-at-nhs-digital#basic-rest).\n\n## Network access\n\nEeRS supplier API endpoints that conform to this API standard are available on the internet.\n\n## Security and authorisation\n\nAll communications must be encrypted using HTTP(S).\n\nEach 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.\nLiaise with the EeRS supplier you are integrating with, to get an API key for their endpoint configuration.\n\n## Onboarding\n\nLiaise with NHSX for onboarding your service into live operation. Please contact NHSX at [digital.podac@nhsx.nhs.uk](mailto:digital.podac@nhsx.nhs.uk).\n\n## Errors\nWe use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:\n\n* 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action\n* 400 to 499 if it failed because of a client error by your application\n* 500 to 599 if it failed because of an error on our server\n\nErrors specific to each API are shown in the Endpoints section, under Response. See our [reference guide](https://digital.nhs.uk/developer/guides-and-documentation/reference-guide#http-status-codes) for more on errors.\n"},"servers":[{"description":"SwaggerHub API Auto Mocking - RW","url":"https://virtserver.swaggerhub.com/Sphinx/Eyecare/1.0"},{"url":"http://localhost:3000"}],"paths":{"/referrals":{"post":{"summary":"Create a referral","operationId":"post-referrals","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/Authorization"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"components/schemas/Response.yaml"},"example":{"referralID":"123e4567-e89b-12d3-a456-426614174000","referralURL":"https://someEeRSSystem/referrals/123e4567-e89b-12d3-a456-426614174000","referralStatus":"incomplete"}}},"headers":{"Accept-Version":{"description":"The version number of the API you wish to call.","schema":{"type":"string","example":"1.0.0"}}}},"500":{"description":"Internal Server Error"},"4XX":{"description":"An error occurred as follows:\n \n| HTTP status | errorMessage | errorCode | Scenario |\n| ----------- |----------------------------------------------------------- |-------------- | ------------------------------------------------------- |\n| 400 | Malformed JSON | E0001 | JSON could not be parsed for processing. It is invalid. |\n| 400 | Empty JSON body | E0002 | No JSON was received in the request body. |\n| 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. | \n| 401 | Authentication failed | E0010 | Either the API-KEY is invalid or the values in the ODS and GOCNumber fields failed authentication. |\n| 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. |\n| 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. |\n| 422 | A data type could not be converted | E0009 | This error is used when the conversion to the target data type cannot be made. |\n","content":{"application/json":{"schema":{"$ref":"components/schemas/Response.yaml"},"example":{"errorMessage":"Malformed JSON","errorCode":"E0001"}}},"headers":{"Accept-Version":{"description":"The version number of the API you wish to call.","schema":{"type":"string"}}}}},"description":"Sends a new referral into the EeRS\n\n ### Create a new referral in the EeRS\n\n **Step 1**: The cinician user decides to create a referral and clicks “refer via EeRS” or similar on the Optometry PMS system\n\n **Step 2**: Optometry PMS gathers the data payload to send via the API\n \n **Step 3**: Optometry PMS identifies the EeRS supplier API to call based on the optometry practice where the practitioner has clicked ‘create EeRS referral’\n \n **Step 4**: Optometry PMS initiates API by sending API key to the EeRS in question with the data payload\n \n **Step 5**: EeRS provides a response 201 with a URL - or an error message\n \n ### Complete the referral in the EeRS \n\n **Step 1**: Optometry PMS launches the URL for the user in a browser\n \n **Step 2**: The user can now see the data rendered in the EeRS, and can complete the referral.\n \n **Step 3**: The user completes the referral using the EeRS.\n \n ### Optometry PMS sender guidance\n\n If there is no value in your Optometry PMS for a non-mandatory nullable field do either one of the following:\n - exclude that field from the JSON\n - use JSON NULL to represent an empty field rather than empty string. \n \n ### EeRS provider guidance\n\n 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.","requestBody":{"content":{"application/json":{"schema":{"$ref":"components/schemas/Referral.yaml"},"example":{"$ref":"components/examples/Referral.json"}}}}}},"/referral/{referralID}/status":{"parameters":[{"schema":{"type":"string"},"name":"referralID","description":"The unique, system-agnostic identifier of the referral. Must be an RCF 4122 compliant UUID.","example":"123e4567-e89b-12d3-a456-426614174000","in":"path","required":true}],"get":{"summary":"Get referral status","parameters":[{"$ref":"#/components/parameters/VersionHeader"},{"$ref":"#/components/parameters/Authorization"}],"tags":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"components/schemas/StatusResponse.yaml"},"example":{"referralStatus":"incomplete"}}},"headers":{"Accept-Version":{"description":"The version number of the API you wish to invoke.","schema":{"type":"string","example":"1.0.0"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"components/schemas/StatusResponse.yaml"},"example":{"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/StatusResponse.yaml"},"example":{"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/StatusResponse.yaml"},"example":{"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"}},"operationId":"get-referral-referralID-status","description":"Returns the status of the referral with the given ID\nA status update can be initiated by a clinician or admin, or set to be initiated automatically for all referrals as desired.\n\n **Step 1**: PMS system requests a status check to a specific referral ID using the same API key as for the referral\n\n **Step 2**: EeRS supplier provides response 200 with the status - or an error message "}}},"security":[{"apikey":[]}],"components":{"securitySchemes":{"apikey":{"type":"apiKey","in":"header","name":"api-key"}},"parameters":{"VersionHeader":{"name":"Accept-Version","description":"The version number of the API you wish to call.","in":"header","schema":{"type":"string","example":"1.0.0"}},"Authorization":{"name":"api-key","description":"The API Key associated with the calling API consumer.","in":"header","schema":{"type":"string","example":"KdsASD78FA5Sjl342kfwreas"}}}}}