Migrating from the NRL v2.8. API to the NRL v3.0. API

Overview

On 1 April 2025 we deprecated our National Record Locator - FHIR API v2.8.0. It is still available for use, and is still fully supported, but we will not be adding any new features. The API will be retired on 1 April 2026, meaning it will not be available for use after that date.

If you need continued access to NRL, we recommend that you migrate your application to use the National Record Locator - FHIR API v3 - Producer API.

We also have a National Record Locator - FHIR API v3 - Consumer API. If you are accessing NRL functionality using the National Care Record Service, you are already using the new NRL v.3.0. consumer API.

Why we have deprecated the NRL v.2.8. API

We’ve built two new APIs that provides equivalent functionality - the NRL v.3.0. Producer and Consumer APIs.

As per our deprecation and retirement policy, we must ensure that public funds are used efficiently and cannot afford to maintain replaced APIs indefinitely.

What deprecated means

Deprecated means:

the API is still available for use
full service levels still apply
we are unlikely to make any updates to it
new integrations are not allowed - although in-flight integrations can continue
we intend to retire it at some point

About the NRL v.3.0. APIs

The NRL v.3.0. APIs are our strategic APIs for accessing disparate patient records from source. They replace the NRL v.2.8. API.

They have a number of benefits over the NRL v.2.8. API, including:

the APIs are microservices built in AWS, as opposed NRL v.2.8. which was built on Spine infrastructure
they are accessible via the APIM platform
they are internet-facing only
our code base is open source
the APIs conform to FHIR - the most modern healthcare interoperability standard
we use the FHIR R4 DocumerReference data model, as opposed to the HL7 STU3 DocumentReference data model
they use OAuth 2.0 with signed JWTs for security, which makes rotating your security credentials easier
it has an easier onboarding process, using the Digital onboarding service, as opposed to using a Supplier Conformance Assurance List (SCAL)
additional new pointer types are available for consumption via the new NRL v3.0. service
we provide support for structured data

Summary of differences

Area	Differences
Service level	NRL v.2.8. was a bronze level service, whereas the new NRL v.3.0. is a gold service, meaning it will be available and supported 24 hours a day, 365 days a year.
Additional pointer types	The NRL v.3.0. APIs provide the ability to consume additional pointer types that are not available via the NRL v.2.8. API. Available now: shared care record summary sheets Coming soon: Lloyd George record folders bookings and referrals imaging reports diagnostic images international patient summaries patient specific protocols ambulance reports discharge summaries
Data model changes	in FHIR R4 '.class' has changed to '.category' there are no cardinality or logical changes - some FHIR cardinality constraints have changed, but we have added business logic to ensure consistency where we used to use 'references', we now have version agnostic system and value pairs and the system will be fixed if you are using the Spine Secure Proxy, you will need to provide your ASID details in the 'context.related' section of the pointer body the value sets in use are on our public Github
Supersede functionality	We have tried to preserve previous behaviours as much as possible, but some subtle changes had been made in response to feedback from users: supersede functionality still exists, and is to be used when you want to delete and re-create a pointer the original pointer ID will now be retained to help with traceability you can no longer supersede a pointer using its master/local ID. This can only be done using the document/logic ID assigned and returned by us
Update functionality	Update functionality is no longer limited - you can update anything except the logical ID of the pointer.
Delete functionality	You can no longer delete a pointer using its master/local ID. This can only be done using the document/logic ID assigned and returned by us.
Search functionality	We now offer new provider search capabilities. These allows users to search for pointers created by their own organisation, to assist with testing. If you want to be able to search for pointers created by other organisations, you will need to use consumer search functionality, which has not changed.
Retrieval functionality	Spine Secure Proxy is still in use for document retrieval. For new use cases (such as the retrieval of Lloyd George record folders, and diagnostic images), additional new retrieval patterns may start to be supported. We hope any new retrieval mechanisms to be built on the APIM platform for ease of integration.
Data Migration	All pointers available on NRL v.2.8. are already available via the new NRL v.3.0., thanks to our 'one directional data sync' solution. For this reason, when providers migrate from the old service to the new service, there won't be any requirements to re-register historic data in bulk.
	The NRL APIs have two test environments: a sandbox for early developer testing, which provides canned responses to a limited number of scenarios. You can use the sandbox without any authorisation, straight from the website. Please note, if you create a pointer in our sandbox, another user could delete it. an integration testing environment for formal integration testing. Other users cannot amend the test data created by you. Both environments are self-service. Access to INT can be requested via your developer account - although in the short term, setting up your permissions to interact with certain pointer types needs our input.
Network access	The NRL v.3.0. APIs are available on the internet only.
Security	The NRL v.3.0. API uses OAuth 2.0 with signed JWTs to authenticate the calling application. You should rotate your JWTs on an ongoing basis but you can do this without our involvement.
API format	The NRL v.3.0. is RESTful and conforms to FHIR R4. To call it you make a simple HTTP request to a named endpoint, and the requests and responses are in JSON format. FHIR libraries are available to make it easier to generate requests and parse responses. XML format is no longer supported.
Onboarding	We have tried to make onboarding to the NRL v.3.0. APIs as quick and easy as possible. In particular: the NRL v.3.0. APIs use our new digital onboarding service, which makes onboarding quicker and more transparent the governance and assurance requirements are virtually identical if you're migrating from the NRL v.2.8. API, you won't need your use cases approving by the Interoperability Advisory Group (IAG) we have onboarding leads and technical specialists on a rota to assist developers who are migrating from the NRL v.2.8. API