Search loading...


Explore and Make use of Nationally Defined Messaging APIs


Development Overview

Development overview.

This section intends to give developers detailed requirements and guidance to interact with the NRL for the creation, management and retrieval of pointers, outlines the information available and lists some pre-requisites for using the NRL service.

In the requirement pages, keywords ‘MUST’, ‘MUST NOT’, ‘REQUIRED’, ‘SHALL’, ‘SHALL NOT’, ‘SHOULD’, ‘SHOULD NOT’, ‘RECOMMENDED’, ‘MAY’ and ‘OPTIONAL’ are to be interpreted as described in RFC 2119, in order to create an NRL compliant system.

NRL Interactions

The NRL supports the following interactions as detailed in the Architectural Overview page:

Interaction HTTP Verb Actor Description
Read GET Consumer Retrieve a single pointer by logical ID.
Search GET Consumer Parameterised search for pointers on the NRL.
Create POST Provider Create an NRL pointer.
Create (Supersede) POST Provider Replace an NRL pointer, changing the status of the replaced pointer to superseded.
Update PATCH Provider Update an NRL pointer to change the status to entered-in-error.
Delete DELETE Provider Delete an NRL pointer.

Explore NRL Interactions

You can explore and test the NRL interactions using Swagger (NRL API Reference Implementation).

Generic Requirements

Endpoint Registration

For an organisation to be able to use the NRL:

  • the system they are using MUST have been accredited through the assurance process.
  • the organisation MUST have been given an endpoint certificate and associated ASID for the environment (INT, DEP, LIVE) they wish to connect to.
  • the organisation’s endpoint MUST have been configured with the required interaction ids and service permissions.

NHS Number

NHS Numbers used within any interaction with the NRL, MUST be traced and verified prior to submission.

Verification of an NHS Number can be achieved using:

The option of using a DBS service is for provider systems only; consumers performing a search operation MUST use either a full PDS Spine compliant system or a Spine Mini Services Provider.

JSON Web Token

A JSON Web Token (JWT) is required for all interaction with the NRL and SSP. All requirements for JWT population can be found on the JSON Web Token Guidance page.

Interaction Content Types

The NRL supports the following MIME types for NRL interactions:


  • application/fhir+xml
  • application/xml+fhir
  • application/xml


  • application/fhir+json
  • application/json+fhir
  • application/json
  • text/json

Response Format

The NRL supports the following methods to allow the client to specify the response format by its MIME type:

  • the HTTP Accept header.
  • the optional _format parameter.

If both are present in the request, the _format parameter overrides the Accept header value in the request. If neither the Accept header nor the _format parameter are supplied by the client system, the NRL server will return data in the default format of application/fhir+xml.


Generic requirements for security, authentication and authorisation are included in the specification on the Security Guidance page.


Requirements on information retrieval formats and retrieval mechanisms are outline in the Information Retrieval section of this specification.

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