Search loading...


Explore and Make use of Nationally Defined Messaging APIs


Release Notes

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


Changes to restructure the Implementation Guide.

  • versionId will be incremeted 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 NRLS API 1.1.0-beta Specification with the DDC March and May 2018 NRLS 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 NRLS Service implementation.
    • Exceptions raised by the Spine Core common requesthandler and not the NRLS 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 NRLS 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.
  • NRLS access token (JWT) enhancements:
    • The NRLS 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 Autherisation page added - NRLS 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 NRLS Server will support paging as a default to break up result-sets that exceed a pre-determined limit.
  • NRLS 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
  • NRLS will not be fronted by SSP i.e. requests to read/write Pointers will not go through the SSP in order to reach NRLS

First release of NRLS FHIR API (STU3) via

  • Project follows the Gov.UK agile delivery phases.


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

Published on NHS Developer Network.

Tags: development

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