Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Search Interaction

To support a parameterised search of the NRL.

References

Consumer interaction to support a parameterised search of the NRL. The search interaction is a FHIR RESTful search 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.

Search Request Headers

Consumer API search 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

Search DocumentReference

Search Parameters

This implementation guide outlines the search parameters for the DocumentReference resource in the table below:

Name Type Description Path
_id id Logical ID of the resource. DocumentReference.id
subject reference Subject (patient) of the DocumentReference. DocumentReference.subject (Patient NHS Number)
custodian reference Organisation which maintains the DocumentReference. DocumentReference.custodian (Organisation ODS Code)
type Coding Information type (SNOMED CT). DocumentReference.type.coding

A search is made using either the _id or subject search parameter.

  • The _id search parameter MUST NOT be used in conjunction with any other search parameter (with the exception of the _format parameter).
  • The custodian and/or type search parameters can only be used in conjunction with the subject search parameter to form a combination search query.

_id

The _id search parameter refers to the logical ID of the DocumentReference resource.

Functionally this search is the equivalent to a simple pointer read operation.

See _id for details on this search parameter. The _id search parameter can be used as follows:

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

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

The _id search parameter cannot be used in conjunction with any other search parameter (with the exception of the _format parameter.)

subject

See reference for details on this search parameter. The subject search parameter can be used as follows:

The subject search parameter MUST follow the format:

https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]

GET [baseUrl]/STU3/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210

Return all DocumentReference resources for a patient with an NHS Number of 9876543210.

subject and type

The subject and type search parameters can be used as follows:

The subject search parameter MUST follow the format:

https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]

The type search parameter MUST follow the format:

[system]|[code]

GET [baseUrl]/STU3/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543210&type.coding=http%3A%2F%2Fsnomed.info%2Fsct%7C736253002

Return all DocumentReference resources for a patient with an NHS Number of 9876543210 and pointer type 'Mental health crisis plan'.

subject and custodian

The subject and custodian search parameters can be used as follows:

The subject search parameter MUST follow the format:

https://demographics.spineservices.nhs.uk/STU3/Patient/[nhsNumber]

The custodian search parameter MUST follow the format:

https://directory.spineservices.nhs.uk/STU3/Organization/[ODS Code]

GET [baseUrl]/STU3/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543210&custodian=https%3A%2F%2Fdirectory.spineservices.nhs.uk%2FSTU3%2FOrganization%2FRR8

Return all DocumentReference resources for a patient with an NHS Number of 9876543210 and pointer owner with ODS code RR8.

Search Response

Success

A successful execution of the search interaction will:

  • return a 200 OK HTTP status code.
  • return a Bundle response boby of type searchset, containing either:
    • A 0 (zero) total value indicating no records matched the search criteria, i.e. an empty Bundle.
    • One or more DocumentReference resources (with a current status) that conform to the NRL DocumentReference FHIR profile.
      • The current versionId will be included.
      • If masterIdentifier and/or relatesTo are set, they will be included.

Failure

The following errors can be triggered when performing this operation:

Example: Single Pointer Response

  • Request was successfully executed (200 OK HTTP status).
  • Response body is a Bundle resource of type searchset containing 1 DocumentReference resource conforming to the NRL-DocumentReference-1 profile.
<Bundle xmlns="http://hl7.org/fhir">
  <id value="dd9724d1-7b61-44e2-9023-b72e6b966018-76563212455590986546" />
  <type value="searchset" />
  <total value="1" />
  <link>
    <relation value="self" />
    <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543210" />
  </link>
  <entry>
    <fullUrl value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261" />
    <resource>
      <DocumentReference>
        <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261" />
        <meta>
          <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1" />
          <version value="1" />
          <lastUpdated value="2016-03-08T15:26:00+01:00" />
        </meta>
        <masterIdentifier>
          <system value="urn:ietf:rfc:3986" />
          <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.7" />
        </masterIdentifier>
        <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>
        <relatesTo>
          <code value="replaces" />
          <target>
            <identifier>
              <system value="urn:ietf:rfc:3986" />
              <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.6" />
            </identifier>
          </target>
        </relatesTo>
        <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>
    </resource>
    <search>
      <mode value="match" />
    </search>
  </entry>
</Bundle>

Example: Multiple Pointers Response

  • Request was successfully executed (200 OK HTTP status).
  • Response body is a Bundle resource of type searchset containing 2 DocumentReference resources conforming to the NRL-DocumentReference-1 profile.
<Bundle xmlns="http://hl7.org/fhir">
  <id value="dd9724d1-7b61-44e2-9023-b72e6b966018-54446768443265458908" />
  <type value="searchset" />
  <total value="2" />
  <link>
    <relation value="self" />
    <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543211" />
  </link>
  <entry>
    <fullUrl value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-58778905432232112312" />
    <resource>
      <DocumentReference>
        <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-58778905432232112312" />
        <meta>
          <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1" />
          <version value="1" />
          <lastUpdated value="2016-03-08T15:26:00+01:00" />
        </meta>
        <masterIdentifier>
          <system value="urn:ietf:rfc:3986" />
          <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.11" />
        </masterIdentifier>
        <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/9876543211" />
        </subject>
        <indexed value="2018-07-01T15: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/MentalhealthCrisisTeam" />
            <creation value="2018-07-01T15:26:00+01:00" />
          </attachment>
          <format>
            <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-FormatCode-1" />
            <code value="urn:nhs-ic:record-contact" />
            <display value="Contact details (HTTP Unsecured)" />
          </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="2017-05-12T13: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>
    </resource>
    <search>
      <mode value="match" />
    </search>
  </entry>
  <entry>
    <fullUrl value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/5303c09e-de28-4622-9416-62ab0b22e15a-54598780989231213433" />
    <resource>
      <DocumentReference>
        <id value="5303c09e-de28-4622-9416-62ab0b22e15a-54598780989231213433" />
        <meta>
          <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1" />
          <version value="1" />
          <lastUpdated value="2016-03-08T15:26:00+01:00" />
        </meta>
        <masterIdentifier>
          <system value="urn:ietf:rfc:3986" />
          <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.10" />
        </masterIdentifier>
        <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/9876543211" />
        </subject>
        <indexed value="2018-07-02T11:25: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>
        <relatesTo>
          <code value="replaces" />
          <target>
            <identifier>
              <system value="urn:ietf:rfc:3986" />
              <value value="urn:oid:1.3.6.1.4.1.21367.2005.3.9" />
            </identifier>
          </target>
        </relatesTo>
        <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" />
            <end value="2017-02-13T14:11:00+01:00" />
          </period>
          <practiceSetting>
            <coding>
              <system value="http://snomed.info/sct" />
              <code value="708168004" />
              <display value="Mental health service" />
            </coding>
          </practiceSetting>
        </context>
      </DocumentReference>
    </resource>
    <search>
      <mode value="match" />
    </search>
  </entry>
</Bundle>

Example: No Pointers Response

  • Request was successfully executed (200 OK HTTP status).
  • Response body is an empty Bundle resource of type searchset containing 0 (zero) DocumentReference resources indicating no record was matched.
<Bundle xmlns="http://hl7.org/fhir">
  <id value="de258b7f-2f0b-4b41-afcb-964d9995fd4f-65447656980012115439" />
  <type value="searchset" />
  <total value="0" />
  <link>
    <relation value="self" />
    <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https%3A%2F%2Fdemographics.spineservices.nhs.uk%2FSTU3%2FPatient%2F9876543213" />
  </link>
</Bundle>

Explore the NRL

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

Tags: fhir pointers for consumers

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