Search loading...


Explore and Make use of Nationally Defined Messaging APIs


Release Notes

Summary release notes of the versions released in NRL API Implementation Guide


  • Add clarification about use of versionId to Supersede interaction page
  • Update ODS code and endpoint requirements guidance
  • Remove SSP prefix from example DocumentReferences
  • Update guidance on constructing SSP URLs and percent-encoding for document retrieval
  • Add clarification about cardinality in JSON
  • Add notes about CodeableConcept data type
  • Updated glossary of terms
  • Update tags and enable filtering by tag name
  • Remove obsolete pages
  • Miscellaneous copy-edits and minor restructuring


  • Renamed metadata ‘Record class’ to ‘Record category’
  • Updated guidance on request headers for the retrieval read interaction
  • Updated guidance on use of CareConnect GET Binary API for unstructured retrieval
  • Added guidance on pointer model versioning
  • Updated guidance on Consumer and Provider interactions on:
    • Solution behaviour page
    • Solution interactions page
    • Development guidance overview page
  • Updated solution principles
  • Added detail on access control and RBAC codes
  • Changed the interaction ID that must be used:
    • for registering Provider document/record retrieval endpoints on SDS
    • for when Consumers perform a look-up of a Provider ASID on SDS
  • Added clarification on using absolute URLs in the Record URL metadata attribute


  • Updated guidance on usage of SNOMED CT concepts in FHIR value sets
  • API interaction examples updated


Changes to record/document retrieval requirements and updated guidance

  • API Breaking Change The custodian search parameter format has been updated
  • API Breaking Change The supported formats for retrieval have been updated
  • API Breaking Change The inclusion of the meta.profile element on the create and supersede interactions are now enforced
  • Consumer guidance on assembling SSP request updated
  • Updated JWT requirements for document/record retrieval via the SSP
  • Change to interaction ID for record retrieval via the SSP
  • Restructuring of record retrieval read interaction guidance
  • Added definition of FHIR meta attributes to the data model
  • Added clarity to the rules on the use of PATCH
  • Added clarity to the use of reference type metadata attributes
  • Added clarity on the use of NHS Number with subject/patient
  • API interaction examples updated
  • Guidance on prerequisites added to API interactions
  • Audit requirements elaborated
  • Phase 1 and Phase 2 overview updated


Changes to record/document retrieval requirements, new API interactions, NRL DocumentReference model changes, and updated guidance.

  • The service name has changed from NRLS (National Record Locator Service) to NRL (National Record Locator)
  • API Breaking Change The FHIR Resource NRLS-DocumentReference-1 uplifted to NRL-DocumentReference-1
    • Data model changes are detailed below
  • API Breaking Change Data model changes
    • Class: now mandatory and persisted by NRL
    • Type: ValueSet URL changed from NRLS-RecordType-1 to NRL-RecordType-1
    • Context: now mandatory
    • Context.PracticeSetting: now mandatory and persisted by NRL
    • Context.Period: now persisted by NRL
    • Content.Format: now mandatory and persisted by NRL
    • Content: has new mandatory extension of ContentStability (NRL-ContentStability-1)
    • RelatesTo: now limited to max of 1
    • RelatesTo.Code: now limited to single code of ‘replaces’
  • FHIR Resource examples (JSON/XML)
    • Source of FHIR Resource examples has been changed
    • FHIR Resource examples are now contained in a shorter scrollable code block
  • Assurance page
    • References to TOM have been changed to SCAL
    • Links to the on-boarding guide have been added
  • Developer Guidance
    • Overview page
      • NHS number verification guidance updated
      • Actor to interaction mapping table updated
    • FHIR Resource page
      • Renamed
      • Additional data model properties detailed
      • Additional valuesets, extensions, and codesystems added
      • Master Identifier added to identifiers section
      • The term ‘Record Status’ has changed to ‘Pointer Status’
    • General API Guidance
      • Error handling updates:
        • Invalid resource section re-structured
        • Added detail for the ‘update interaction’ errors
        • Added Patient mismatch errors
        • Added masterIdentifier errors
        • Inactive DocumentReference guidance added
        • New data model error handling details added
    • New API Feature Retrieval of Records/Documents Guidance now documented in a new section under Developer Guidance, which includes:
      • An overview of retrieval
      • Read interaction requirements
      • Provider guidance
      • Consumer guidance
      • Pointer format code guidance
  • API Interactions
    • Update interaction page has been renamed to ‘Create (Supersede)’
      • New API Feature ‘Supersede’ now supports supersede by logical id
      • Now details additional error responses
      • API Breaking Change A ‘supersede’ with multiple relatesTo properties will now be rejected
      • API Breaking Change A ‘supersede’ with a relatesTo property containing a code other than ‘replaces’ will be rejected
      • New ‘Update interaction’ page created, see below
    • New API Feature RESTful ‘read’ by logical id now supported which returns a single DocumentReference resource
    • New API Feature RESTful ‘update’ now supported - using the HTTP PATCH verb
      • HTTP PATCH supports update by logical id and master identifier
    • Create interaction
      • Page details additional error responses
      • API Breaking Change Format of Location response header has been changed to [baseUrl]/DocumentReference/[id]
    • Delete interaction
      • New API Feature Now supports RESTful delete by logical id i.e. DELETE [baseUrl]/DocumentReference/[id]
      • Requirements have been moved into a single section
    • Search interaction
      • Now only returns DocumentReference’s that have a ‘status’ of current
      • DocumentReference’s with a format code that indicates the referenced content is to be retrieved via the SSP will have its url property modified to reflect this.
      • These changes also apply to Read Interaction
      • Bundle response now includes additional attributes:
        • Self link added
        • Search.mode added
        • Resource.fullUrl added
  • Integrate with spine
    • Security page
      • This page has been moved from Developer guidance to the Integrate with spine section
      • Overview section added
      • Further clarity on which protocols can be used
      • Updated the allowed cipher suite list
      • Guidance added for those that already have a NHS Digital supplied X.509 certificate
      • Guidance document links have been fixed
    • Access Token and Audit page renamed to Access Token (Audit has moved to its own page)
    • New audit page added
    • PDS Guidance updated
    • Authentication guidance and requirements updated to reflect content retrieval and related service name changes
  • Pointer Guidance
    • More clarity on handling errors
    • More clarity on use of the master identifier property
  • Pointer Lifecycle
    • Removed reference to transition from “entered-in-error” to current
    • More clarity on meaning of each status
    • More guidance on deleting pointers
  • Pointer Maintenance
    • More clarity on what deleting pointers does
    • More clarity on handling lineages
    • Detailed the new ‘update’ and ‘supersede’ interactions
  • Solution
    • Data model updated to reflect DocumentReference changes detailed above
    • Clarity around caching data added


Changes to restructure the Implementation Guide.

  • versionId will be incremented during a supersede transaction - Create API interaction updated to align with implementation.
  • 500 Internal server error HTTP response guidance modified to match Spine Core output - Spine does not return an operation outcome.
  • NRLS-DocumentReference-1 FHIR profile element guidance explicitly supports element.


Changes to restructure the Implementation Guide.

  • Introduction of C# example code.
  • Warnings about encoding query parameters.
  • Additional guidance regarding JWT added.


Changes to restructure the Implementation Guide.

  • Wording change for Internal errors.
  • Clearer guidance for pointer transitions (Current to Superseded).
  • Explanation added for the Superseded status.
  • Addition of example for deleting a pointer using masterIdentifier.
  • Pointer error handling and pointer lineage guidance added.


Changes to restructure the Implementation Guide.

  • Additional guidance added to the Data model page.
  • Cardinality corrected for Related Documents
  • Added Status to the model.
  • Description updated for the elements.
  • Addition of new API Interaction section to describe the RESTful functionalities (Create, Delete, Search, and Update).
  • API Guidance > Search page
  • Format guidance added for Custodian.
  • Inclusion of the _summary=count functionality.
  • New Pointer-related pages added a new Development Guidance menu.
  • General API Guidance
  • Error guidance has been restructured to be more informative to the reader.
  • Addition of INTERNAL_SERVER_ERROR and the response format.
  • Exception tables moved from the API Interaction page to the General API Guidance page.
  • Deploy menu option removed
  • Assure menu option removed


Changes to re-align the NRL API 1.1.0-beta Specification with the DDC March and May 2018 NRL Service Development Iterations:

  • Provider and Consumer API Read interaction removed.
  • Provider and Consumer API Search interaction changes:
    • _count Search parameter removed
    • _id Search parameter added
    • type Search parameter added
    • patient search parameter reverted to subject
    • Bundle type searchset does not support:
      • Encoded client search parameters in returned bundle using the self link.
      • The identity of resources in the entry using the fullUrl element.
      • Resources matched in a successful search using the search.mode element
  • Provider API Update interaction removed.
  • Provider API Delete interaction changes:
    • Now supports conditional delete interaction. Allows a provider to delete an existing pointer based on the search parameter _id which refers to the logical id of the pointer.
  • Spine response codes changes:
    • Amended for all Provider and Consumer API interactions
    • Successful Provider Create and Delete interactions now support positive response code values conveyed in the response body Spine-OperationOutcome-1 payload:
    • Error Handling section updated to reflect API re-alignment with DDC NRL Service implementation.
    • Exceptions raised by the Spine Core common requesthandler and not the NRL Service will be supported by the default Spine OperationOutcome spine-operationoutcome-1-0 profile which binds to the default Spine ValueSet spine-response-code-1-0. Codes include:
  • Pagination removed from Provider and Consumer search API.
  • CapabilityStatement conformance functionality removed from this release.
  • For this release the NRL Service returns data as the default format of XML.
  • NRLS-DocumentReference-1 FHIR profile upversioned to 1.1.0. Changes as follows:
    • ValueSet-NRLS-RecordType-1 replaces ValueSet/CarePlanType-1
    • ValueSet-NRLS-RecordType-1 supports a single SNOMED concept: 736253002 - Mental health crisis plan (record artifact).
    • All NRLS-DocumentReference-1 API examples updated to support record type: Mental health crisis plan (record artifact).
  • Solution Interactions diagrams updated.
  • NRL access token (JWT) enhancements:
    • The NRL access token conforms to the Spine JWT definition.
    • New section Access Tokens and Audit (JWT) added which replaces the Cross Organisation Audit & Provenance section.
  • Assurance Process overview added to specification.

Sprint 6 Summary:

  • Concept of direct and indirect pointers removed from API. Changes to the Data Model and the NRLS-DocumentReference-1 FHIR profile as follows:
    • RecordRetrievalMode CodeableConcept functionality removed from the NRLS-DocumentReference-1 FHIR profile.
    • The following dependent FHIR assets have been removed from NHS FHIR Server and implementation guide:
      • Extension-NRLS-RecordRetrievalMode-1
      • ValueSet-NRLS-RecordRetrievalMode-1
      • CodeSystem-NRLS-RecordRetrievalMode-1
  • Consumer Provider API XML/ JSON examples added
  • HTTP request headers amendments:
    • Ssp-TraceID, Ssp-InteractionID, Ssp-Version - dropped from specification
    • Ssp-From and Ssp-To - Header name change to fromASID and toASID
    • Error Handling section reflects these changes
  • Consumer and Provider API INVALID_PARAMETER error response code aligned to 400 BAD REQUEST HTTP response code.


Sprint 5 summary:

  • Error Handling section added to ‘General API Guidance’ page.
  • Consumer and Provider API error response examples refined.
  • Provider API Create and Update responses amended.
  • VersionId guidance added.
  • CapabilityStatement page updated.
  • Auditing section added to ‘Solution Behaviour’ page.
  • Audit Trail section added to ‘Cross Organization Audit & Provenance’ page.
  • JWT Claims updated:
    • ‘device’ claim added - this is the Identifier (ASID) of the system where the request originates.
    • ‘sub’ claim specification/ example has been updated.
  • Authentication and Authorisation page added - NRL strategic approach to align with ‘Care Access Service’ which will become NHS Digital’s national Authentication and Authorisation service.
  • JSON and XML examples added to Reference section.


Sprint 4 summary:

  • Consumer and Provider APIs ‘Success’ Search Response amended to support an empty bundle if search returns no matches.
  • Consumer API Search examples added.
  • Development Guidance section now supports ‘General API Guidance’ page. This includes implementation guide ‘notational conventions’ and RESTful API ‘content types’ sections.
  • The ‘Accept’ HTTP request header conformance amended to ‘MAY’.

Sprint 3 summary:

  • Consumer and Provider APIs now support the ‘patient’ Search parameter. This replaces the ‘subject’ parameter.
  • Consumer and Provider APIs Search operations will not mandate the ‘_count’ parameter. It is expected that the NRL Server will support paging as a default to break up result-sets that exceed a pre-determined limit.
  • NRL API Conformance updated.

Sprint 3 early release summary:

  • Record retrieval via the SSP will not be mandated.

Sprint 2 summary:

  • Read Operation added to Consumer API.
  • Provider and Consumer API search capabilities aligned.
  • Pagination added to Provider and Consumer search API.
  • If-Match header (containing ETag) dropped from Provider API update and delete operations.
  • Security Guidance updated: TLSv1.2 must be supported for all new Spine interfaces and new cyphers added.
  • Implementation Guide semver use updated. No longer using pre-release numeric identifiers.

Sprint 1 ‘internal’ review feedback amendments include:

  • References to SDS removed
  • Solution principles changed to reflect that the Provider controls the Record retrieval mechanism strategy
  • NRL will not be fronted by SSP i.e. requests to read/write Pointers will not go through the SSP in order to reach NRL

First release of NRL FHIR API (STU3) via

  • Project follows the Gov.UK agile delivery phases.


First draft of NRL DMS (Version 1.0 Draft A) created to support development of the Spine 2 POC National Record Locator interface.

Published on NHS Developer Network.

Tags: overview

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