Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Search Interaction

To support parameterised search of the NRL.

References

API to support parameterised search of the NRL. This functionality is available for both consumer and provider systems.

Search Request Headers

Provider 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, this will be one of the following application/fhir+json or application/fhir+xml. See the RESTful API Content types section. MAY
Authorization The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see Access Tokens (JWT) for details. MUST
fromASID Client System ASID MUST
toASID The Spine ASID MUST

Search DocumentReference

Though the NRL does not keep a version history of each DocumentReference each one does hold a versionId.

In responding to a search request the NRL server will populate the versionId of each matching DocumentReference.

Search Parameters

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

Name Type Description Conformance Path
_id token The logical id of the resource SHOULD DocumentReference.id
custodian reference Organization which maintains the document reference MAY DocumentReference.custodian(Organization)
subject reference Who/what is the subject of the document SHOULD DocumentReference.subject
(Patient)
type token Kind of document (SNOMED CT) MAY DocumentReference.type
_summary Summary Total number of matching results MAY N/A

When the _id search parameter is used by a client it SHALL only be used as a single search parameter and SHALL not be used in conjunction with any other search parameter to form part of a combination search query with the exception of ‘_format’ parameter.

When the subject parameter is used by a client it MAY be used in conjunction with the custodian and type search parameters to form a combination search query. The custodian and type search parameters SHALL only be used to form combination search queries.

_id

The search parameter _id refers to the logical id of the DocumentReference resource and can be used when the search context specifies the DocumentReference resource type.

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

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

When the _id search parameter is used by a client, this search parameter SHALL only be used as a single search parameter and SHALL not be used in conjunction with any other parameter to form part of a combination search query with the exception of ‘_format’ parameter.

subject

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

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

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

subject and custodian

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&custodian.identifier=https://fhir.nhs.uk/Id/ods-organization-code%7CRR8

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

subject and type

GET [baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&type.coding=http://snomed.info/sct%7C736253002

Return all DocumentReference records for a patient with NHS Number of 9876543210 and a pointer type of Mental Health Crisis plan.

_summary

The search parameter _summary allows the client to retrieve the number of DocumentReferences that match a given search.

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

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

Return a count of resources for a patient with a NHS Number of 9876543210

The _summary search parameter must be set to the value ‘count’ to retrieve the number of matching results. Other FHIR values for this search parameter are not supported.

Search Response

Success:

  • SHALL return a 200 OK HTTP status code on successful execution of the interaction.
  • SHALL return a Bundle of type searchset, containing either:
    • One or more documentReference resource that conforms to the NRL-DocumentReference-1 profile and has the status value “current”; or
    • A ‘0’ (zero) total value indicating no record was matched i.e. an empty ‘Bundle’.

  • Where a documentReference is returned, it SHALL include the versionId of the current version of the documentReference resource

  • When a Consumer retrieves a DocumentReference if the masterIdentifier is set then it should be included in the returned DocumentReference

  • When a Consumer retrieves a DocumentReference if the relatesTo is set then it should be included in the returned DocumentReference

Failure:

The following errors can be triggered when performing this operation:

Example Scenario

An authorised NRL Consumer searches for a patient’s relevant health record using the NRL to discover potentially vital information to support a patient’s emergency crisis care.

Request Query

Return all DocumentReference resources (pointers) for a patient with a NHS Number of 9876543210. The format of the response body will be XML.

cURL

curl -H 'Accept: application/fhir+xml' -H 'Authorization: BEARER [token]' -X GET  '[baseUrl]/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210&_format=xml'

Query Response Http Headers

HTTP/1.1 200 OK
Server: nginx/1.10.0 (Ubuntu)
Date: Mon, 19 Jun 2017 08:36:12 GMT
Content-Type: application/fhir+xml;charset=utf-8
Last-Modified: Mon, 19 Jun 2017 08:36:12 GMT

Query Response

Single Pointer (DocumentReference) Returned:
  • HTTP 200-Request was successfully executed
  • Bundle resource of type searchset containing a total value ‘1’ DocumentReference resource that conforms 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://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"/>
    </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"/>
                </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 (record artifact)"/>
                    </coding>
                </type>
                <class>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="734163000"/>
                        <display value="Care plan (record artifact)"/>
                    </coding>
                </class>
                <subject>
                    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"/>
                </subject>
                <created value="2016-03-08T15:26:00+01:00"/>
                <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://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/MentalhealthCrisisPlanReportRGD.pdf"/>
                        <title value="Mental health Crisis Plan Report"/>
                        <creation value="2016-03-08T15:26:00+01:00"/>
                    </attachment>
                    <format>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1"/>
                        <code value="direct:https://www.iso.org/standard/63534.html"/>
                        <display value="PDF (Publicly accessible)"/>
                    </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="892811000000109"/>
                            <display value="Adult mental health service"/>
                        </coding>
                    </practiceSetting>
                </context>
            </DocumentReference>
        </resource>
        <search>
            <mode value="match"/>
        </search>
    </entry>
</Bundle>
Multiple Pointers (DocumentReference) Returned:
  • HTTP 200-Request was successfully executed
  • Bundle resource of type searchset containing a total value ‘2’ DocumentReference resources that conform to the NRL-DocumentReference-1 profile
<Bundle
    xmlns="http://hl7.org/fhir"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://hl7.org/fhir file:///C:/Users/supa1/Desktop/STU3%20Schemas/bundle.xsd">
    <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://demographics.spineservices.nhs.uk/STU3/Patient/9876543211"/>
    </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"/>
                </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 (record artifact)"/>
                    </coding>
                </type>
                <class>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="734163000"/>
                        <display value="Care plan (record artifact)"/>
                    </coding>
                </class>
                <subject>
                    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543211"/>
                </subject>
                <created value="2018-07-01T15:26:00+01:00"/>
                <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://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/MentalhealthCrisisPlanReportRGD.pdf"/>
                        <title value="Mental health Crisis Plan Report"/>
                        <creation value="2018-07-01T15:26:00+01:00"/>
                    </attachment>
                    <format>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1"/>
                        <code value="direct:https://www.iso.org/standard/63534.html"/>
                        <display value="PDF (Publicly accessible)"/>
                    </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="892811000000109"/>
                            <display value="Adult 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"/>
                </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 (record artifact)"/>
                    </coding>
                </type>
                <class>
                    <coding>
                        <system value="http://snomed.info/sct"/>
                        <code value="734163000"/>
                        <display value="Care plan (record artifact)"/>
                    </coding>
                </class>
                <subject>
                    <reference value="https://demographics.spineservices.nhs.uk/STU3/Patient/9876543211"/>
                </subject>
                <created value="2018-07-02T11:25:00+01:00"/>
                <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://spine-proxy.national.ncrs.nhs.uk/p1.nhs.uk/MentalhealthCrisisPlanReportRGD.pdf"/>
                        <title value="Mental health Crisis Plan Report"/>
                        <creation value="2018-07-02T11:25:00+01:00"/>
                    </attachment>
                    <format>
                        <system value="https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1"/>
                        <code value="direct:https://www.iso.org/standard/63534.html"/>
                        <display value="PDF (Publicly accessible)"/>
                    </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="892811000000109"/>
                            <display value="Adult mental health service"/>
                        </coding>
                    </practiceSetting>
                </context>
            </DocumentReference>
        </resource>
        <search>
            <mode value="match"/>
        </search>
    </entry>
</Bundle>
No Record (pointer) Matched:
  • HTTP 200-Request was successfully executed
  • Empty bundle resource of type searchset containing a ‘0’ (zero) total value 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://demographics.spineservices.nhs.uk/STU3/Patient/9876543213"/>
    </link>
</Bundle>
Error Response (OperationOutcome) Returned:
  • HTTP 400-Bad Request. Invalid Parameter.
  • OperationOutcome resource that conforms to the ‘Spine-OperationOutcome-1’ profile if the search cannot be executed (not that there is no match)
<OperationOutcome
    xmlns="http://hl7.org/fhir">
    <id value="5a4171ac-486e-11e8-9ffc-6c3be5a609f5-34326129638901216693"/>
    <meta>
        <profile value="https://fhir.nhs.uk/STU3/StructureDefinition/Spine-OperationOutcome-1"/>
    </meta>
    <issue>
        <severity value="error"/>
        <code value="invalid"/>
        <details>
            <coding>
                <system value="https://fhir.nhs.uk/STU3/CodeSystem/Spine-ErrorOrWarningCode-1"/>
                <code value="INVALID_PARAMETER"/>
                <display value="Invalid parameter"/>
            </coding>
        </details>
        <diagnostics value="The given resource URL does not conform to the expected format - https://demographics.spineservices.nhs.uk/STU3/Patient/[NHS Number]"/>
    </issue>
</OperationOutcome>

See the general API guidance for all HTTP Error response codes supported by the NRL.

_summary=count response:
  • Response body SHALL return a valid XML or JSON formatted Bundle of type searchset, containing a bundle that reports the total number of resources that match in Bundle.total, but with no entries, and no prev/next/last links. Note that the Bundle.total only include the total number of matching DocumentReferences.

Examples

  • 3 DocumentReferences exist for patient with NHS number passed into the search
<Bundle
    xmlns="http://hl7.org/fhir">
    <id value="de258b7f-2f0b-4b41-afcb-964d9995fdf-98874345667801234356"/>
    <type value="searchset"/>
    <total value="3"/>
    <link>
        <relation value="self"/>
        <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543214&amp;_summary=count"/>
    </link>
</Bundle> 
  • 0 DocumentReferences exist for patient with NHS number passed into the search
<Bundle
    xmlns="http://hl7.org/fhir">
    <id value="de258b7f-2f0b-4b41-afcb-964d5995fd4f-16547321986190065387"/>
    <type value="searchset"/>
    <total value="0"/>
    <link>
        <relation value="self"/>
        <url value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference?subject=https://demographics.spineservices.nhs.uk/STU3/Patient/9876543213&amp;_summary=count"/>
    </link>
</Bundle> 

Code Examples

GET Pointers with C#

The following code samples are taken from the NRL Demonstrator application which has both Consumer and Provider client implementations built in. More information about the design solution can be found on the NRL Demonstrator Wiki

First we generate a base pointer request model that includes the patients NHS Number used for the subject parameter. The NHS Number is obtained through a stub PDS Trace performed within the Demonstrator Consumer system.

Then we call our DocumentReference service GetPointersBundle method which will build a GET command request and then start the call to the NRL API.

Demonstrator/Demonstrator.Services/Service/Nrls/PointerService.cs#L34-L36 view raw
var pointerRequest = NrlsPointerRequest.Search(request.OrgCode, request.Id, null, request.Asid, null);

var pointerResponse = await _docRefService.GetPointersBundle(pointerRequest);

Once we have received pointers from the NRL when then look up the custodian (and author) organisation details using the ODS Code’s held within each pointer via a stub ODS lookup. We can then present actual organisation details to the end users.

Calling the NRL
Using our GET command request model we create a connection to the NRL using HttpClient.

You can view the common connection code example here.

Explore the NRL
You can explore and test the NRL GET command using Swagger in our Reference implementation.


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