Sunsetting policy

The NHS e-Referral Service (e-RS) is an evolving, publicly-funded national system, critical to the NHS.

The API we offer must be maintained and managed cost-effectively. This means that API endpoints will be deprecated and retired over time.

Partners must migrate away from deprecated API endpoints. In exceptional circumstances you will also be expected to respond to breaking changes.

This policy builds upon the general NHS API deprecation and retirement policy.

An API endpoint may be deprecated if it is:

• redundant with the introduction of a new endpoint which provides equivalent or enhanced capabilities

• not fit for purpose, for example because it doesn't include important use-cases

• insecure or a security risk

• not being used or has limited usage

When an API endpoint is deprecated:

• we will publish a deprecation notice which includes a deprecation and retirement date
• a migration guide will be produced
• the endpoint will still be available for use
• normal service levels will still apply
• further updates to the endpoint are unlikely to be made
• new integrations will not be permitted - partners already in the latter stages of onboarding will be allowed to complete integration

For details on endpoints that are currently being considered for deprecation or retirement, see our deprecation notices.

The deprecation period is 12 months.

The retirement date is the date at the end of this period at which the API endpoints will reach end-of-life and be taken out of service.  At this point, the API endpoint will no longer be available for use.

During the deprecation period partners are expected to follow the migration guide and onboard with the new API endpoint. A lighter weight assurance policy will be available for migrations, provided no new functionality is to be adopted.

The aim is for partners to have migrated away from the deprecated API endpoints before the retirement date. 

Partners unable to migrate away from an API endpoint before its retirement date should contact the API partners team within 6 weeks of the deprecation notice: [email protected].

The e-RS is an evolving system. Functionality is being added and updated to meet the demands of the NHS. As such, the e-RS API will need to adapt to meet these needs.

When a proposed change is not backwards compatible, we will look to introduce a new version of the endpoint. This will maintain the behaviour of the existing endpoint version. The deprecation and retirement policy will be followed to prompt the migration of partners to the new endpoint version.

In exceptional cases, it may be necessary to make a breaking change to an existing endpoint.

This could be because:

• an immediate privacy or security risk has been identified
• a critical functional change to the e-RS has been identified that cannot reasonably be accommodated in any other way

The deprecation period length will be assessed on a case-by-case basis when this occurs. At the end of this period the changes will be applied to the existing endpoint. Other aspects will follow the standard deprecation and retirement process.

Partners unable to update their integration before the changes are applied should email the API partners team within 6 weeks of the deprecation notice: [email protected].