Search loading...


Explore and Make use of Nationally Defined Messaging APIs


API Update Interaction

To support the update of NRL pointers.



Provider interaction to support the update of NRL pointers. The update functionality will be used in cases where a provider wishes to update a pointer status value, changing it from current to entered-in-error. The update interaction is a FHIR RESTful patch 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.

Update Request Headers

Provider API update 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

Update Operation

Providers systems MUST only update pointers for records where they are the pointer owner (custodian).

For all update requests the custodian ODS code in the DocumentReference MUST be affiliated with the Client System ASID value in the fromASID HTTP request header sent to the NRL.

Update by id

The API supports the update by ID interaction, which allows a provider to delete an existing pointer based on the logical ID of the pointer.

The logical ID can be obtained from the Location header which is contained in the create response - see the Create API Interaction for details.

To accomplish this, the provider issues an HTTP PATCH as shown:

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

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

Conditional Update by masterIdentifier

The API supports the conditional update interaction which allows a provider to update a pointer using the masterIdentifier, negating the requirement to persist or query the NRL to obtain the generated logical ID for the pointer.

The query parameters should be used as shown:

  • [nhsNumber] - The NHS Number of the patient related to the DocumentReference.
  • [system] - The namespace of the masterIdentifier value associated with the DocumentReference.
  • [value] - The value of the masterIdentifier associated with the DocumentReference.
PATCH [baseUrl]/STU3/DocumentReference?

Update the DocumentReference status for a pointer with a subject and identifier.

Request Body

Provider systems MUST construct a FHIRPath PATCH Parameters FHIR resource and submit this to the NRL using the FHIR RESTful patch interaction.

The Parameters resource MUST meet the following conditions:

Element Cardinality Additional Guidance
parameter 1..1 1..1 Fixed value: operation
parameter.part 3..3 See table below.

Three part elements are required as follows: part.value[x] name part.value[x] value
Fixed value: type Fixed value: valueCode Fixed value: replace
Fixed value: path Fixed value: valueString Fixed value: DocumentReference.status
Fixed value: value Fixed value: valueString Fixed value: entered-in-error

XML FHIRPath PATCH Parameters Resource Example

<Parameters xmlns="">
    <name value="operation" />
      <name value="type" />
      <valueCode value="replace" />
      <name value="path" />
      <valueString value="DocumentReference.status" />
      <name value="value" />
      <valueString value="entered-in-error" />

JSON FHIRPath PATCH Parameters Resource Example

  "resourceType": "Parameters",
  "parameter": [
      "name": "operation",
      "part": [
          "name": "type",
          "valueCode": "replace"
          "name": "path",
          "valueString": "DocumentReference.status"
          "name": "value",
          "valueString": "entered-in-error"



A successful execution of the update interaction will:

  • return a 200 OK HTTP status code confirming the entry has been successfully updated in the NRL.
  • return a response body containing an OperationOutcome resource (see below for full details).
  • increment the resource’s versionId by 1.


The OperationOutcome resource in the response body will conform to the Spine-OperationOutcome-1 FHIR resource:

Element Content
id A UUID for this OperationOutcome.
meta.profile Fixed value:
issue.severity Fixed value: information
issue.code Fixed value: informational
issue.details.coding.system Fixed value:
issue.details.coding.code Fixed value: RESOURCE_UPDATED
issue.details.coding.display Fixed value: Resource has been updated
issue.details.text A Spine internal message UUID which can be used to identify the client’s create transaction within Spine. A client system SHOULD reference this UUID in any related incidents raised with the National Service Desk. The UUID will be used to retrieve log entries that relate to a specific client transaction.
issue.diagnostics Dynamic value: Successfully updated resource DocumentReference: [URL]

Example success response body (XML)

<OperationOutcome xmlns="">
  <id value="1500ab25-b9e5-4515-9f11-3ca0adddbcce-00000000000000000000" />
    <profile value="" />
    <severity value="information" />
    <code value="informational" />
        <system value="" />
        <code value="RESOURCE_UPDATED" />
        <display value="Resource has been updated" />
      <text value="911f55e4-d754-4fee-b044-f8aad32ad309" />
    <diagnostics value="Successfully updated resource DocumentReference:" />

Example success response body (JSON)

  "resourceType": "OperationOutcome",
  "id": "1500ab25-b9e5-4515-9f11-3ca0adddbcce-00000000000000000000",
  "meta": {
    "profile": [
  "issue": [
      "severity": "information",
      "code": "informational",
      "details": {
        "coding": [
            "system": "",
            "code": "RESOURCE_UPDATED",
            "display": "Resource has been updated"
        "text": "911f55e4-d754-4fee-b044-f8aad32ad309"
      "diagnostics": "Successfully updated resource DocumentReference:"


The following errors can be triggered when performing this operation:

Explore the NRL

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

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