Search loading...

API Hub

Explore and Make use of Nationally Defined Messaging APIs

 

API Supersede Interaction

To support the superseding of NRL pointers

References

Create (Supersede)

Provider interaction to support superseding NRL pointers. Create with Supersede (abbreviated to Supersede) is an extension of the Create Interaction. The Supersede functionality will be used in cases where a Provider wishes to replace one DocumentReference with another, newer one.

Pre-requisites

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

Supersede Request Headers

Provider API supersede 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. OPTIONAL
Authorization The Authorization header will carry the base64url encoded JSON web token required for audit on the spine - see Access Tokens (JWT) for details. REQUIRED
fromASID Client System ASID REQUIRED
toASID The Spine ASID REQUIRED

Supersede Operation

The NRL API does not allow a true update i.e. the HTTP PUT verb is not supported. A pointer can be replaced by superseding it with a newer pointer that contains the updated attributes.

A Provider transitions an existing Pointer’s status from current to superseded as part of the act of creating its replacement. In effect the POSTing of a new DocumentReference provides a means to specify an existing DocumentReference whose status should be moved to superseded. Concretely this is achieved as follows:

  1. Provider assembles a new DocumentReference resource
  2. Provider populates the relatesTo property with a new target element which holds –
    • a reference that is the logical identifier of the existing DocumentReference or an identifier that is the masterIdentifier of the existing DocumentReference
    • the action code “replaces”
  3. Provider POSTs the DocumentReference resource
  4. NRL will transactionally -
    1. create the new DocumentReference marking it as current
    2. resolve the existing DocumentReference using the relatesTo.target
    3. mark that DocumentReference as superseded

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

The target property within the relatesTo attribute must be either a reference or a FHIR identifier, depending on whether a provider chooses to supersede by logical ID or supersede by master identifier.

Supersede by Logical ID

To supersede by logical ID, the relatesTo.target attribute on the DocumentReference should be a FHIR reference property i.e. an absolute literal reference to a DocumentReference held within NRL. The value should be a URL in the form of read by logical ID.

Example of a DocumentReference relatesTo property populated using a FHIR reference.

{
    "relatesTo": [
        {
            "code": "replaces",
            "target": {
                "reference": "https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"
            }
        }
    ]
}

Supersede by Master Identifier

To supersede by Master identifier, the relatesTo.target attribute on the DocumentReference should be a FHIR identifier. The Identifier is interpreted as the masterIdentifier of a DocumentReference held within NRL.

Example of a DocumentReference relatesTo property populated using a FHIR identifier.

{
    "relatesTo": [
        {
            "code": "replaces",
            "target": {
                "identifier": {
                    "system": "urn:ietf:rfc:3986",
                    "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.6"
                }
            }
        }
    ]
}

In both cases (use of reference or identifier values) the patient NHS Number on the new (to be created) DocumentReference and the DocumentReference being superseded must match. For more details, see Error Handling Guidance.

If both the target.reference property and the target.identifier property are populated then the NRL will use the target.reference property to resolve the DocumentReference. If a DocumentReference is found, then the MasterIdentifier of the returned DocumentReference must match the identifier in the relatesTo collection. For more details, see Error Handling Guidance.

The NRL will only accept one relatesTo element. Requests that contain multiple relatesTo elements will be rejected. For more details, see Error Handling Guidance.

Supersede by Logical ID XML example

An XML Example of a DocumentReference resource that supersedes an existing DocumentReference by Logical ID.

Please note the addition of the relatesTo property within the DocumentReference example below.

<DocumentReference>
    <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>
    <relatesTo>
        <code value="replaces"/>
        <target>
            <reference value="https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"/>
        </target>
    </relatesTo>
    <content>
        <attachment>
            <contentType value="application/pdf"/>
            <url value="https://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.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>

Supersede by Logical ID JSON example

A JSON Example of a DocumentReference resource that supersedes an existing DocumentReference by Logical ID.

Please note the addition of the relatesTo property within the DocumentReference example below.

{
    "resourceType": "DocumentReference",
    "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:00+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://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.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"
                        }
                    ]
                }
            }
        }
    ],
    "relatesTo": [
        {
            "code": "replaces",
            "target": {
                "reference": "https://psis-sync.national.ncrs.nhs.uk/DocumentReference/0353e505-f7be-4c20-8f4e-337e79a32c51-76009894321256642261"
            }
        }
    ],
    "context": {
        "period": {
            "start": "2016-03-07T13:34:00+01:00"
        },
        "practiceSetting": {
            "coding": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "708168004",
                    "display": "Mental health service"
                }
            ]
        }
    }
}

Supersede by Master Identifier XML example

An XML Example of a DocumentReference resource that supersedes an existing DocumentReference by Master Identifier.

Please note the addition of the relatesTo property within the DocumentReference example below.

<DocumentReference>
    <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"/>
        </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://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.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>

Supersede by Master Identifier JSON example

A JSON Example of a DocumentReference resource that supersedes an existing DocumentReference by Master Identifier.

Please note the addition of the relatesTo property within the DocumentReference example below.

{
    "resourceType": "DocumentReference",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/STU3/StructureDefinition/NRL-DocumentReference-1"
        ]
    },
    "masterIdentifier": {
        "system": "urn:ietf:rfc:3986",
        "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.7"
    },
    "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:00+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://spine-proxy.national.ncrs.nhs.uk/https%3A%2F%2Fp1.nhs.uk%2FMentalhealthCrisisPlanReport.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"
                        }
                    ]
                }
            }
        }
    ],
    "relatesTo": [
        {
            "code": "replaces",
            "target": {
                "identifier": {
                    "system": "urn:ietf:rfc:3986",
                    "value": "urn:oid:1.3.6.1.4.1.21367.2005.3.6"
                }
            }
        }
    ],
    "context": {
        "period": {
            "start": "2016-03-07T13:34:00+01:00"
        },
        "practiceSetting": {
            "coding": [
                {
                    "system": "http://snomed.info/sct",
                    "code": "708168004",
                    "display": "Mental health service"
                }
            ]
        }
    }
}

Response

Success and Failure:

As an extension of the Create interaction, the success and failure responses are the same for Supersede as they are for Create.

See Create Interaction - Responses for details of the expected response behaviours and codes.

Code Examples

When either Creating or Superseding a Pointer, the same HTTP POST verb is used.

See Create Interaction - Code Examples for an example of POSTing a pointer.


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