Search loading...


Explore and Make use of Nationally Defined Messaging APIs


API Read Interaction

To support the retrieval of an NRL pointer.



Consumer interaction to support the retrieval of a single NRL pointer. The read interaction is a FHIR RESTful read interaction.


In addition to the requirements on this page, the general guidance and requirements detailed on the Development Overview page MUST be followed when using this interaction.

Read Request Headers

Consumer API read requests support the following HTTP request headers:

Header Value Conformance
Accept The Accept header indicates the format of the response the client is able to understand, if set, this must be either application/fhir+json or application/fhir+xml. OPTIONAL
Authorization The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see the JSON Web Token Guidance page for details. REQUIRED
fromASID Client System ASID. REQUIRED

Read Operation

The read interaction allows a consumer to retrieve a single pointer (DocumentReference) by logical ID.

The consumer must issue an HTTP GET as shown:

GET [baseUrl]/STU3/DocumentReference/da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142

Read the DocumentReference resource for a pointer with the logical id of 'da2b6e8a-3c8f-11e8-baae-6c3be5a609f5-584d385036514c383142'.

Note the status of the pointer must be current for the pointer to be retrieved.

Read Response


A successful execution of the read interaction will:

  • return a 200 OK HTTP status code.
  • return a response body containing a DocumentReference resource which conforms to the NRL-DocumentReference-1 FHIR profile and has the status current.

Example Successful Response:

  <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261" />
    <profile value="" />
    <version value="1" />
    <lastUpdated value="2016-03-08T15:26:00+01:00" />
    <system value="urn:ietf:rfc:3986" />
    <value value="urn:oid:" />
  <status value="current" />
      <system value="" />
      <code value="736253002" />
      <display value="Mental health crisis plan" />
      <system value="" />
      <code value="734163000" />
      <display value="Care plan" />
    <reference value="" />
  <indexed value="2016-03-08T15:26:01+01:00" />
    <reference value="" />
    <reference value="" />
    <code value="replaces" />
        <system value="urn:ietf:rfc:3986" />
        <value value="urn:oid:" />
      <contentType value="application/pdf" />
      <url value="" />
      <creation value="2016-03-08T15:26:00+01:00" />
      <system value="" />
      <code value="urn:nhs-ic:unstructured" />
      <display value="Unstructured Document" />
    <extension url="">
          <system value="" />
          <code value="static" />
          <display value="Static" />
      <start value="2016-03-07T13:34:00+01:00" />
        <system value="" />
        <code value="708168004" />
        <display value="Mental health service" />


The following errors can be triggered when performing this operation:

Explore the NRL

You can explore and test the read interaction using Swagger in the NRL API Reference Implementation.

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