Stage 1.6 - Review our integration criteria

This page describes criteria which you will need to be aware of when integrating with our API.

These criteria ensure that:

• your software is compatible with the e-Referral Service
• information can be shared securely and efficiently between systems

Some sections may not be relevant to your use case but have been provided here for completeness.

1.1 Audit

An audit log is a record of events and changes. Logs contain historical information that can be used to reconstruct the timeline of an incident.

We have created clear guidance on our expectation for gathering and retaining audit. Audit logging is assessed as part of the assurance process.

1.2 Application-restricted (unattended) access

Due to the way in which application-restricted, unattended access has been designed, partners have some additional responsibility.

These criteria must be reviewed and met if your software solution plans to use this access mode.

1.3 Supplier Conformance Assessment List (SCAL)

The SCAL is a document that asks for technical information about your software. It helps ensure your software is safe, secure and meets information governance standards. 

The purpose of the SCAL is to ensure that every partner has thought through their solution and produced each of the assets that may want to be seen by prospective customers as part of a procurement.  It is also a confirmation that business rules have been understood and adhered which can't be validated by the API itself.

When you sign the Connection Agreement (see Stage 4 - Release), the SCAL becomes part of your legally binding agreement with NHS England.

1.4 Pathway Start Date

The e-Referral Pathway Start Date is a derived value of when the Referral To Treatment (RTT) clock starts. Find out how e-RS derives the pathway start date here.

You can supply an optional, alternate pathway start date when creating a referral via Create referral (A011).

This may be because steps, such as reviews, take place early in your business process. Which means the clock started earlier than when the e-RS referral is created. Providing an alternate pathway start date ensures the correct date is recorded and used in other systems.

If you intend to use this function, you must seek approval from the NHS England National Elective Care team before developing your solution. They will ensure the RTT date is being calculated in line with National RTT rules.

You can contact the Elective Care team on [email protected].

Please note, the Elective Care team have an SLA of 20 days for these requests.

2.1 Max payload size

API Management enforces a strict 10MB limit on response sizes. 10MB relates to approximately 7,500 entries on a worklist.

Most of our API endpoints will operate well within this specification.

However, the referral worklist and the advice and guidance requests worklist endpoints could return much larger responses if the worklists aren't managed carefully.

2.2 PDS integration

Depending on your use case, there may be a need to query the Personal Demographics Service (PDS).

This is to gather and confirm a patient's demographic details.

The e-RS API will only ever provide NHS numbers for patient identification purposes.

PDS must be used to obtain personal data such as name, address, date of birth and registered GP.

This is a separate API which is also accessible via API Management.

In some cases, PDS integration will be required before integrating with the e-Referral Service.

2.3 Rate limits

The e-Referral Service API limits the number of transactions you can make. This protects our service against excessive use and denial-of-service attacks. It also encourages you to use our API efficiently.

Our rate limit for the production environment is 10 requests per second per application. There are further restrictions for specific endpoints that are detailed in the documentation.

All requests you make from your application are counted towards this limit. If you go over the rate limit you'll receive a response with an HTTP status of 429 (Too Many Requests).

If you have problems with rate limits, contact the team at [email protected] with your volumetrics. We can discuss your application design and decide whether it's appropriate to amend your rate limit.

Our API follows a product lifecycle. Endpoints get created, see some usage and are eventually discontinued.

We use a gradual sunsetting process when we deprecate and retire an endpoint in our API catalogue.

We have a sunsetting policy that provides more information on the process.

Get support on integrating with our API by checking out our developer community.

You can:

• search and find answers to your query
• post your own questions
• join a community of professionals with similar objectives