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)

API to support superseding NRL pointers. This functionality is only available for providers. 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.

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. 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

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

Providers systems SHALL 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 further detail, 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 further details, see Error Handling Guidance.

The NRL will only accept one relatesTo element. Requests that contain multiple relatesTo elements will be rejected. For further detail, 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>
    <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76567690043214346653"/>
    <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 (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>
            <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/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>

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 (record artifact)"
            }
        ]
    },
    "class": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "734163000",
                "display": "Care plan (record artifact)"
            }
        ]
    },
    "subject": {
        "reference": "https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"
    },
    "created": "2016-03-08T15:26:00+01:00",
    "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/p1.nhs.uk/MentalHealthCrisisPlanReportRGD.pdf",
                "title": "Mental health Crisis Plan Report",
                "creation": "2016-03-08T15:26:00+01:00"
            },
            "format": {
                "system": "https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1",
                "code": "direct:https://www.iso.org/standard/63534.html",
                "display": "PDF (Publicly accessible)"
            },
            "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": "892811000000109",
                    "display": "Adult 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>
    <id value="0353e505-f7be-4c20-8f4e-337e79a32c51-76567690043214346653"/>
    <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>

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 (record artifact)"
            }
        ]
    },
    "class": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "734163000",
                "display": "Care plan (record artifact)"
            }
        ]
    },
    "subject": {
        "reference": "https://demographics.spineservices.nhs.uk/STU3/Patient/9876543210"
    },
    "created": "2016-03-08T15:26:00+01:00",
    "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/p1.nhs.uk/MentalHealthCrisisPlanReportRGD.pdf",
                "title": "Mental health Crisis Plan Report",
                "creation": "2016-03-08T15:26:00+01:00"
            },
            "format": {
                "system": "https://fhir.nhs.uk/STU3/CodeSystem/NRL-Format-1",
                "code": "direct:https://www.iso.org/standard/63534.html",
                "display": "PDF (Publicly accessible)"
            },
            "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": "892811000000109",
                    "display": "Adult 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