Search loading...


Explore and Make use of Nationally Defined Messaging APIs


Frequently Asked Questions

A set of common questions and answers regarding the e-Referral APIs
Category         Question                                 Answer
Overview Can I see the NHS Digital roadmap for the APIs? The NHS Digital roadmap for the APIs can be found on the NHS e-Referral Service Integration page on the NHS Digital Systems and Services website.
Overview Which APIs are currently available? Please see the API Endpoint Catalogue for a comprehensive list of Alpha and Live APIs.
Overview How can I register for further interest and receive future integration updates as they become available? Please contact the NHS e-Referral Service API Integration Team directly.
Overview I have a specific scenario I want to talk through, who should I contact? Please contact the NHS e-Referral Service API Integration Team directly.
Overview I have a question that is not listed here, who can I ask? Please contact the NHS e-Referral Service API Integration Team directly.
e-Referral What does the NHS e-Referral Service do? Please find more information about what functionality the NHS e-Referral Service provides here.
e-Referral How do I contact the Platforms Support Desk? Please visit the Assurance Support Portal. The Assurance Support Portal is available via HSCN/N3 only.
Assurance What is the API assurance approach? What do I need to fill in to get assurance of my solution? How can we achieve compliance for our system? You will need to complete the following documents: TOM, Connection Agreement, End User Policy, and Data Sharing. When you are ready to start this process, please contact the Integration Team and an Implementation Manager will be assigned to you to support you through this process. Please visit the Assurance Approach page in the Assure section for further details.
Assurance What is the TOM? This is the Target Operating Model which is a light-weight framework used for you to self-assure your own system confirming it meets the requirements and passes compliance. For more information please visit the Target Operating Model page in the Assure section.
Authentication In order to use the APIs, do I need to be logged on with the smartcard at all times or does it merely require the smartcard UUID to authenticate the user? The user will need to be logged on with the smartcard at all times to use the APIs. Having said this, we are currently having discussions around unattended (system-to-system) calls and will be able to provide more information soon.
Connecting Can I access the APIs from outside the UK? Current infrastructure access does not allow overseas companies as it is currently predicated on N3/HSCN network connectivity, Information Governance Statement of Compliance (IGSoC), the use of smartcards and having clinical sponsorship in place. This may change through the next year when we look to transition our infrastructure over to the cloud, but this is in its initial planning stage and no timescales have been communicated yet. Please see the Business Partners page for more information.
Connecting How can I get started getting access to the APIs? - I don’t have any e-RS/DEV1 smart cards You will need to request smartcards from the Platforms Support Desk. Please find details on the Get Connected page.
Connecting How can I access the APIs? - I have e-RS/DEV1 smartcards but no spine endpoint nor test pack You will need to create a CSR using your FQDN and fill in an EPR form and request Platforms Support Desk to register your endpoint. You will receive endpoint certificate, MHS Party Key and ASID details in return. Please find details on the Get Connected page.
Connecting How can I access the APIs? - I have e-RS/DEV1 smart cards, a spine endpoint and a test pack Once you have an endpoint registration certificate, you will need to create a key pair by following the instructions in the “NHS e-RS API Connectivity Guide” document and then you can use the information about the API resource models in the “NHS e-RS API Structure” document to call the APIs. Please find details on the Get Connected page.
Connecting I already have an e-RS/DEV1 smartcard, do I need another one to access the APIs? If you have already got a smartcard for the e-RS/DEV1 environment, please provide Platforms Support Desk the UUID of the smartcard so that they can assign specific roles to it and also provide a test pack for you to access the NHS e-Referral Service APIs.
Connecting Can I use my e-RS/LIVE smartcards with the e-RS/DEV1 environment? No, you will need new smartcards as a smartcard can only be linked to a single environment (DEV, INT, DEP, TRAIN and LIVE). For further information on the available Path-To-Live environments, please visit the Assurance Support Portal. The Assurance Support Portal is available via HSCN/N3 only.
Connecting What is Postman? Can I connect using my own solution instead? Postman is a Google Chrome app for interacting with HTTP APIs. It presents you with a friendly GUI for constructing requests and reading responses. We ask Partners to use either Postman or our In House developed API Client Demonstrator tool to establish initial connectivity with the APIs after which you can use your own solution to talk to the APIs. You can play around and view the sample source code for the APIs using the API Client Demonstrator tool for your prototype. Please learn more about Postman on their official website.
Connecting What is the API Client Demonstrator? The API Client Demonstrator (aka Quick Connect) is an in-house tool built to demonstrate the e-RS APIs, and their interaction with the NHS e-Referral Service. It covers the major user journeys: from creating referrals, to downloading and triaging. It is developed using Java, and the source code is available on request. In order for the tool to run on your machine, you will need a keypair in JKS or PKCS#8 format (i.e. endpoint certificate and private key), runme.bat and application.yml files. Please contact the NHS e-Referral Service API Integration Team for more details. Please note: this tool is unsupported, and intended purely for demonstration purposes.
Connecting Who should we contact if we encounter issues during development phase? Please contact the Platforms Support Desk detailing the problem. They will raise an incident log for you, in order to record progress and keep you updated. If the issue is urgent/blocking you, please ensure you mention this in your request so they can prioritise it correctly.
Costs Is there any cost associated with utilising the APIs? No, the use of the APIs is free.
Service I can access the APIs, what’s next? How do I create a Service? For more information about using the APIs, please go through the “e-RS Overview” PowerPoint and/or watch the video located on the NHS e-Referral Service website.
Service I have a Service, how can I link it to the NHS Test Patient Administration System (PAS)? Once you have created the service please send the Service ID to the Platforms Support Desk who will be able to link it to a Test PAS System for you to book appointments against.
Service What is the next step once we have a working solution in the e-RS/DEV1 environment? Once you have a suitable solution, you will need to: 1. Demo it to us (please contact the NHS e-Referral Service API Integration Team directly to arrange this). 2. Start the Compliance process, e.g. fill in the other tabs on the TOM, sign the other assurance documents. 3. Contact us so we can help you get connected to e-RS/INT1. A witness test pack will be provided for you to prove the solution is working as per the requirements.
Technology What is an API? API stands for Application Programming Interface. The API is a web service that receives requests and sends responses. From your users perspective, APIs allow them to complete an action without leaving your system. The system uses messages in the JSON format to talk to the API.
Technology What is JSON? JSON stands for JavaScript Object Notation. It is a syntax for storing and exchanging data as text, written with a notation that resembles how the language JavaScript stores objects. The benefits are wide support across all modern web services and a light-weight data transfer.

All content is available under the Open Government Licence v3.0, except where otherwise stated