API Create Interaction

To support the creation of NRL pointers.

References

NHS Digital Profile:
NRL-DocumentReference-1

HL7 FHIR STU3 Resource(s):
DocumentReference

User Stories:
-

Create

Provider interaction to support the creation of NRL pointers. The create interaction is a FHIR RESTful create interaction.

Prerequisites

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.

Create Request Headers

Provider API create 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
`toASID`	The Spine ASID.	REQUIRED

Create Operation

POST [baseUrl]/STU3/DocumentReference

Provider systems MUST:

construct and send a new pointer (DocumentReference) resource that conforms to the NRL-DocumentReference-1 profile and submit this to the NRL using the FHIR RESTful create interaction.
include all of the mandatory data-elements contained in the NRL-DocumentReference-1 profile when constructing a DocumentReference. The mandatory data-elements are detailed on the Developer FHIR Resource page.
follow all population guidance as outlined on the Developer FHIR Resource page when constructing a DocumentReference.
only create pointers for records where they are the pointer owner (custodian).

For all create 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.

XML Example of a New DocumentReference Resource (Pointer)

<DocumentReference xmlns="http://hl7.org/fhir">
  <id value="c037a0cb-0c77-4976-83a1-a5d2703e6aa3-23325861873450086113" />
  <meta>
    <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1" />
  </meta>
  <status value="current" />
  <type>
    <coding>
      <system value="http://snomed.info/sct" />
      <code value="736253002" />
      <display value="Mental health crisis plan" />
    </coding>
  </type>
  <class>
    <coding>
      <system value="http://snomed.info/sct" />
      <code value="734163000" />
      <display value="Care plan" />
    </coding>
  </class>
  <subject>
    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210" />
  </subject>
  <indexed value="2016-03-08T15:26:01+01:00" />
  <author>
    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RGD" />
  </author>
  <custodian>
    <reference value="https://directory.spineservices.nhs.uk/STU3/Organization/RR8" />
  </custodian>
  <content>
    <attachment>
      <contentType value="application/pdf" />
      <url value="https://p1.nhs.uk/MentalhealthCrisisPlanReport.pdf" />
      <creation value="2016-03-08T15:26:00+01:00" />
    </attachment>
    <format>
      <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1" />
      <code value="urn:nhs-ic:unstructured" />
      <display value="Unstructured Document" />
    </format>
    <extension url="https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1">
      <valueCodeableConcept>
        <coding>
          <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1" />
          <code value="static" />
          <display value="Static" />
        </coding>
      </valueCodeableConcept>
    </extension>
  </content>
  <context>
    <period>
      <start value="2016-03-07T13:34:00+01:00" />
    </period>
    <practiceSetting>
      <coding>
        <system value="http://snomed.info/sct" />
        <code value="708168004" />
        <display value="Mental health service" />
      </coding>
    </practiceSetting>
  </context>
</DocumentReference>

JSON Example of a New DocumentReference Resource (Pointer)

{
  "resourceType": "DocumentReference",
  "id": "c037a0cb-0c77-4976-83a1-a5d2703e6aa3-23325861873450086113",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"
    ]
  },
  "status": "current",
  "type": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "736253002",
        "display": "Mental health crisis plan"
      }
    ]
  },
  "class": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "734163000",
        "display": "Care plan"
      }
    ]
  },
  "subject": {
    "reference": "https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"
  },
  "indexed": "2016-03-08T15:26:01+01:00",
  "author": [
    {
      "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/RGD"
    }
  ],
  "custodian": {
    "reference": "https://directory.spineservices.nhs.uk/STU3/Organization/RR8"
  },
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "url": "https://p1.nhs.uk/MentalhealthCrisisPlanReport.pdf",
        "creation": "2016-03-08T15:26:00+01:00"
      },
      "format": {
        "system": "https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1",
        "code": "urn:nhs-ic:unstructured",
        "display": "Unstructured Document"
      },
      "extension": [
        {
          "url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-NRL-ContentStability-1",
          "valueCodeableConcept": {
            "coding": [
              {
                "system": "https://fhir.nhs.uk/STU3/CodeSystem/NRL-ContentStability-1",
                "code": "static",
                "display": "Static"
              }
            ]
          }
        }
      ]
    }
  ],
  "context": {
    "period": {
      "start": "2016-03-07T13:34:00+01:00"
    },
    "practiceSetting": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "708168004",
          "display": "Mental health service"
        }
      ]
    }
  }
}

Create Response

Success

A successful execution of the create interaction will return:

a 201 CREATED HTTP status code confirming the entry has been successfully created in the NRL.
a response body containing an OperationOutcome resource (see below for full details).
an HTTP Location response header containing the full resolvable URL to the newly created ‘single’ DocumentReference:
- The URL will contain the ‘server’ assigned logical id of the new DocumentReference resource.
- The URL format will be: https://[host]/[path]/[id].
- An example Location response header:
  - https://psis-sync.national.ncrs.nhs.uk/DocumentReference/297c3492-3b78-11e8-b333-6c3be5a609f5-54477876544511209789

When a resource has been created it will have a versionId of 1.

Note: The versionId is an integer that is assigned and maintained by the NRL server. When a new DocumentReference is created the server assigns it a versionId of 1. The versionId will be incremented during an update or supersede transaction. See API Interaction - Update and API Interaction - Supersede for more details on these transactions.

The NRL server will ignore any versionId value sent by a client in a create interaction. Instead, the server will ensure that the newly assigned versionId adheres to the rules laid out above.

OperationOutcome

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: `https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1`
`issue.severity`	Fixed value: `information`
`issue.code`	Fixed value: `informational`
`issue.details.coding.system`	Fixed value: `https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1`
`issue.details.coding.code`	Fixed value: `RESOURCE_CREATED`
`issue.details.coding.display`	Fixed value: `New resource created`
`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`	Fixed value: `Successfully created resource DocumentReference`

Example success response body (XML)

<OperationOutcome xmlns="http://hl7.org/fhir">
  <id value="ca613912-e0fe-4ad3-a5b2-378a2f2824c3-00000000000000000000" />
  <meta>
    <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1" />
  </meta>
  <issue>
    <severity value="information" />
    <code value="informational" />
    <details>
      <coding>
        <system value="https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1" />
        <code value="RESOURCE_CREATED" />
        <display value="New resource created" />
      </coding>
      <text value="3de126fa-b5f5-4783-b67f-30c02b865016" />
    </details>
    <diagnostics value="Successfully created resource DocumentReference" />
  </issue>
</OperationOutcome>

Example success response body (JSON)

{
  "resourceType": "OperationOutcome",
  "id": "ca613912-e0fe-4ad3-a5b2-378a2f2824c3-00000000000000000000",
  "meta": {
    "profile": [
      "https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1"
    ]
  },
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "details": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1",
            "code": "RESOURCE_CREATED",
            "display": "New resource created"
          }
        ],
        "text": "3de126fa-b5f5-4783-b67f-30c02b865016"
      },
      "diagnostics": "Successfully created resource DocumentReference"
    }
  ]
}

Failure

The following errors can be triggered when performing this operation:

Explore the NRL

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

Tags:

API Hub

Explore and Make use of Nationally Defined Messaging APIs