All Interactions

Verify Latest SCR

This interaction verifies that the locally held SCR is the latest normal version. If it is not, the interaction returns the latest version. This is the main interaction for GP systems, as the calling client system is very likely to already hold the latest SCR.

Endpoint
https://[baseURL]/DocumentReference

DQ - what is the baseURL for the SCR FHIR API?

Parameters
patient: NHSNo
identifier: UUID of latest SCR for patient on calling system
Requirement
GP systems SHALL supply their latest SCR UUID as a query parameter, so that the majority of calls verify the SCR is the latest normal version and API traffic is minimised

DN - Assume we're working in JSON

Client view of Verify Latest SCR sequence diagram

verify_client

Example Verify Latest SCR call

Verify UUID matches latest on Spine

GET https://[baseURL]/DocumentReference?
 patient=9990001234&
 identifier=C058D90F-E526-4A27-A46E-E86229096AA
 /HTTP/1

Example Verify Latest SCR response - Confirm Latest

Confirming that client has latest normal version

HTTP/1.1 200 OK
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "id": "78caaa2e-8cfc-4588-aaa3-52efbbf32845",
  "fhir_comments": [
    " a Bundled Verify DocumentRef with confirm latest SCR "
  ],
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://[baseURL]/DocumentReference/fa7eafcd-1294-433e-ab46-4db95b58635c",
      "resource": {
        "resourceType": "DocumentReference",
        "id": "fa7eafcd-1294-433e-ab46-4db95b58635c",
        "_id": {
          "fhir_comments": [
            " logical id of this DocumentReference instance "
          ]
        },
        "masterIdentifier": {
          "fhir_comments": [
            " identifier GUID for the SCR latest instance (needs a namingSystem(s) or is it just urn:uuid?) "
          ],
          "system": "https://fhir.nhs.uk/Id/nhsSCRUUID",
          "value": "C058D90F-E526-4A27-A46E-E86229096AAC",
          "_value": {
            "fhir_comments": [
              " Do we care about case here? "
            ]
          }
        },
        "status": "current",
        "type": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "196981000000101",
              "display": " General Practice Summary"
            }
          ]
        },
        "subject": {
          "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9990001234"
          }
        },
        "content": [
          {
            "attachment": {
              "url": "https://[baseURL]/DocumentReference?patient=9990001234",
              "_url": {
                "fhir_comments": [
                  " url points to the Retrieve Latest SCR endpoint with constructed patient search parameter"
                ]
              }
            }
          }
        ],
        "context": {
          "event": [
            {
              "coding": [
                {
                "system": "http://snomed.info/sct",
                "code": "196981000000101",
                "display": " General Practice Summary"
                }
              ]
            }
          ]
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Example Verify Latest SCR response - Not Latest

Supplying the client with latest normal version

HTTP/1.1 200 OK
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "id": "78caaa2e-8cfc-4588-aaa3-52efbbf32845",
  "fhir_comments": [
    " a Bundled Verify DocumentRef with in-lined latest SCR placeholder "
  ],
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://[baseURL]/DocumentReference/fa7eafcd-1294-433e-ab46-4db95b58635c",
      "resource": {
        "resourceType": "DocumentReference",
        "id": "fa7eafcd-1294-433e-ab46-4db95b58635c",
        "_id": {
          "fhir_comments": [
            " logical id of this DocumentReference instance "
          ]
        },
        "masterIdentifier": {
          "fhir_comments": [
            " identifier GUID for the SCR latest instance (needs a namingSystem(s) or is it just urn:uuid?) "
          ],
          "system": "https://fhir.nhs.uk/Id/nhsSCRUUID",
          "value": "C058D90F-E526-4A27-A46E-E86229096AAC",
          "_value": {
            "fhir_comments": [
              " Do we care about case here? "
            ]
          }
        },
        "status": "current",
        "type": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "196981000000101",
              "display": " General Practice Summary"
            }
          ]
        },
        "subject": {
          "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9990001234"
          }
        },
        "content": [
          {
            "attachment": {
              "contentType": "application/fhir+json",
              "_contentType": {
                "fhir_comments": [
                  " contentType MUST hold the Mime type of any in-lined data"
                ]
              },
              "data": "[large base64encoded binary representation of the latest SCR FHIR Document]",
              "title": "GP Summary",
              "creation": "2020-08-20T16:00:00+00:00"
            }
          }
        ],
        "context": {
          "event": [
            {
              "coding": [
                {
                "system": "http://snomed.info/sct",
                "code": "196981000000101",
                "display": " General Practice Summary"
                }
              ]
            }
          ]
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Spine view of Verify Latest SCR sequence diagram

verify_spine

Retrieve Latest SCR

This interaction returns the latest normal SCR. It is intended for clients which don't have local GP Summaries available e.g. in an Ambulance SCR client app.

Endpoint
https://[baseURL]/DocumentReference
Parameters
patient: NHSNo

Client view of Retrieve Latest SCR sequence diagram

retrieve_client

Example Retrieve Latest SCR call

GET https://[baseURL]/DocumentReference?
 patient=9990001234
 /HTTP/1

Example Retrieve Latest SCR response

Supplying the client with latest version

HTTP/1.1 200 OK
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "id": "78caaa2e-8cfc-4588-aaa3-52efbbf32845",
  "fhir_comments": [
    " a Bundled Retrieve DocumentRef with in-lined latest SCR placeholder "
  ],
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://[baseURL]/DocumentReference/fa7eafcd-1294-433e-ab46-4db95b58635c",
      "resource": {
        "resourceType": "DocumentReference",
        "id": "fa7eafcd-1294-433e-ab46-4db95b58635c",
        "_id": {
          "fhir_comments": [
            " logical id of this DocumentReference instance "
          ]
        },
        "masterIdentifier": {
          "fhir_comments": [
            " identifier GUID for the SCR latest instance (needs a namingSystem(s) or is it just urn:uuid?) "
          ],
          "system": "https://fhir.nhs.uk/Id/nhsSCRUUID",
          "value": "C058D90F-E526-4A27-A46E-E86229096AAC",
          "_value": {
            "fhir_comments": [
              " Do we care about case here? "
            ]
          }
        },
        "status": "current",
        "type": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "196981000000101",
              "display": " General Practice Summary"
            }
          ]
        },
        "subject": {
          "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9990001234"
          }
        },
        "content": [
          {
            "attachment": {
              "contentType": "application/fhir+json",
              "_contentType": {
                "fhir_comments": [
                  " contentType MUST hold the Mime type of any in-lined data"
                ]
              },
              "data": "[large base64encoded binary representation of the latest SCR FHIR Document]",
              "title": "GP Summary",
              "creation": "2020-08-20T16:00:00+00:00"
            }
          }
        ],
        "context": {
          "event": [
            {
              "coding": [
                {
                "system": "http://snomed.info/sct",
                "code": "196981000000101",
                "display": " General Practice Summary"
                }
              ]
            }
          ]
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Spine view of Retrieve Latest SCR sequence diagram

retrieve_spine

Get SCR Id

This interaction returns the universally unique identifier (UUID) of the latest version GP Summary held for the patient.

Endpoint
https://[baseURL]/DocumentReference
Parameters
patient: NHSNo
Query
GET https://[baseUrl]/DocumentReference?patient=https://fhir.nhs.uk/Id/nhs-number|[nhsNo]&type=http://snomed.info/sct|196981000000101&_sort=date&_count=1

Idiomatically, this says: get me the pointer to the latest GP Summary

Client view of Get SCR Id sequence diagram

GetSCRIdClient

Example Get SCR Id call

GET https://[baseURL]/DocumentReference?
 patient=https://fhir.nhs.uk/Id/nhs-number|9990001234&
 &type=http://snomed.info/sct|196981000000101&
 _sort=date&
 _count=1
 /HTTP/1

Example Get SCR Id response

Returns a DocumentReference pointer to the latest GP Summary document.

HTTP/1.1 200 OK
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "id": "78caaa2e-8cfc-4588-aaa3-52efbbf32845",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://[baseURL]/DocumentReference/fa7eafcd-1294-433e-ab46-4db95b58635c",
      "resource": {
        "resourceType": "DocumentReference",
        "id": "fa7eafcd-1294-433e-ab46-4db95b58635c",
        "masterIdentifier": {
          "system": "https://fhir.nhs.uk/Id/nhsSCRUUID",
          "value": "C058D90F-E526-4A27-A46E-E86229096AAC"
        },
        "status": "current",
        "type": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "196981000000101",
              "display": " General Practice Summary"
            }
          ]
        },
        "subject": {
          "identifier": {
            "system": "https://fhir.nhs.uk/Id/nhs-number",
            "value": "9990001234"
          }
        },
        "securityLabel": [
          {
            "coding": [
              {
              "system": "https://fhir.nhs.uk/CodeSystem/SCR-ACSPermission",
              "code": "Ask"
              }
            ]
          }
        ],
        "content": [
          {
            "attachment": {
              "url": "https://[baseUrl]/Bundle?composition.identifier=C058D90F-E526-4A27-A46E-E86229096AAC$composition.subject:Patient.identifier=https://fhir.nhs.uk/Id/nhs-number|9990001234"
            }
          }
        ],
        "context": {
          "event": [
            {
              "coding": [
                {
                "system": "http://snomed.info/sct",
                "code": "196981000000101",
                "display": " General Practice Summary"
                }
              ]
            }
          ]
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Spine view of Verify Latest SCR sequence diagram

GetSCRIdSpine

Get SCR Document

This interaction returns the latest normal SCR.

Endpoint
https://[baseUrl]/Bundle
Parameters
document: uuid
patient: NHSNo
Query
GET https://[baseUrl]/Bundle?composition.identifier=[uuid]$composition.subject:Patient.identifier=https://fhir.nhs.uk/Id/nhs-number|[nhsNo]

Idiomatically, this says: get me the GP Summary with this identifier, for the patient with this NHS number

Client view of Retrieve Latest SCR sequence diagram

GetSCRDocumentClient

Example Get SCR Document call

GET https://[baseUrl]/Bundle?
 composition.identifier=[uuid]$
 composition.subject:Patient.identifier=https://fhir.nhs.uk/Id/nhs-number|9990001234
 /HTTP/1

Example Get SCR Document response

HTTP/1.1 200 OK
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "Bundle",
  "id": "78caaa2e-8cfc-4588-aaa3-52efbbf32845",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "fullUrl": "https://[baseURL]/DocumentReference/fa7eafcd-1294-433e-ab46-4db95b58635c",
      "resource": {
        "resourceType": "Bundle",
        "id": "f61e545c-d52c-4b62-9668-3dcc6c27fc50",
        "identifier": {
            "system": "https://tools.ietf.org/html/rfc4122",
            "value": "1ff370b6-fc5b-40a1-9721-2a942e301666"
        },
        "type": "document",
        "timestamp": "2007-03-15T01:00:00Z",
        "entry":  [
            {
                "fullUrl": "urn:uuid:2880eedf-76f0-4f38-9681-dc158e937da7",
                        "resource": {
                            "resourceType": "Composition",
                            "id": "2880eedf-76f0-4f38-9681-dc158e937da7",
                            "identifier": {
                                "system": "https://tools.ietf.org/html/rfc4122",
                                "value": "C058D90F-E526-4A27-A46E-E86229096AAC"
                            },
                            "status": "final",
                            "type": {
                                "coding":  [
                                    {
                                        "system": "http://snomed.info/sct",
                                        "code": "196981000000101",
                                        "display": "General Practice Summary"
                                    }
                                ]
                            },
                            "date": "2007-03-15T01:00:00Z",
                            "subject": {
                                "reference": "urn:uuid:b6f5dd89-fc3a-466d-baad-126c0aac46fc"
                            },
                            "author":  [
                                {
                                    "reference": "urn:uuid:83c26c8f-ee72-4534-8891-0136972b2106",
                                    "display": "Dr Steve Jones"
                                }
                            ],
                            "title": "General Practice Summary",
                            "section":  [
                                {
                                    "title": "General Practice Summary",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Allergies and Adverse Reactions",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Repeat Medication",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Acute Medication",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Discontinued Repeat Medication",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Risks to Care professional or Third Party",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Diagnoses",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Problems and issues",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Clinical Observation and Findings",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Treatments",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Investigations",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Provision of Advice and Information to Patients and Carers",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Personal Preferences",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Social and Personal Circumstances",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Services, Care Professionals and Carers",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Lifestyle",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                },
                                {
                                    "title": "Family History",
                                    "text": {
                                        "status": "generated",
                                        "comment": "--- We have skipped the narrative for better readability of the resource ---"
                                    }
                                }
                            ]
                        }
                    },
                    {
                        "fullUrl": "urn:uuid:83c26c8f-ee72-4534-8891-0136972b2106",
                        "resource": {
                            "resourceType": "PractitionerRole",
                            "id": "83c26c8f-ee72-4534-8891-0136972b2106",
                            "identifier":  [
                                {
                                    "system": "http://fhir.nhs.net/Id/sds-role-profile-id",
                                    "value": "673836492727"
                                }
                            ],
                            "practitioner": {
                                "reference": "urn:uuid:b1a41ee5-b88b-4f66-bd83-24343bf63dd8"
                            }
                        }
                    },
                    {
                        "fullUrl": "urn:uuid:b1a41ee5-b88b-4f66-bd83-24343bf63dd8",
                        "resource": {
                            "resourceType": "Practitioner",
                            "id": "b1a41ee5-b88b-4f66-bd83-24343bf63dd8",
                            "name":  [
                                {
                                    "family": "Jones",
                                    "given":  [
                                        "Steve"
                                    ],
                                    "prefix":  [
                                        "Dr"
                                    ]
                                }
                            ]
                        }
                    },
                    {
                        "fullUrl": "urn:uuid:b6f5dd89-fc3a-466d-baad-126c0aac46fc",
                        "resource": {
                            "resourceType": "Patient",
                            "id": "b6f5dd89-fc3a-466d-baad-126c0aac46fc",
                            "identifier":  [
                                {
                                    "extension":  [
                                        {
                                            "url": "https://fhir.hl7.org.uk/STU3/StructureDefinition/Extension-CareConnect-NHSNumberVerificationStatus-1",
                                            "valueCodeableConcept": {
                                                "coding":  [
                                                    {
                                                        "system": "https://fhir.hl7.org.uk/STU3/CodeSystem/CareConnect-NHSNumberVerificationStatus-1",
                                                        "code": "01",
                                                        "display": "Number present and verified"
                                                    }
                                                ]
                                            }
                                        }
                                    ],
                                    "system": "https://fhir.nhs.uk/Id/nhs-number",
                                    "value": "9900004948"
                                }
                            ]
                        }
                    }
                ]
          },
      "search": {
        "mode": "match"
      }
    }
  ]
}

Spine view of Get SCR Document sequence diagram

GetSCRDocumentSpine

Set Permission

The SCR API provides a custom operation, setPermission, to allow update of Permission to view for GP Summaries held for the patient. Possible values are Yes, No, Ask.

setPermission is specified in the OperationDefinition setPermission

Endpoint
https://[baseURL]/$setPermission
Parameters
patient: NHSNo
Permission value: Yes | No | Ask Using coded values from CodeSystem CodeSystem-SCR-ACSPermission
Query
POST https://[baseUrl]/$setPermission

Client view of Get SCR Id sequence diagram

setPermission

Example setPermission call

POST https://[baseUrl]/$setPermission /HTTP/1

Example setPermission call payload

setPermission passes in-parameter arguments as a Parameter payload

{
    "resourceType": "Parameters",
    "parameter":  [
        {
            "name": "setPermissions",
            "part":  [
                {
                    "name": "nhsNumber",
                    "valueString": "999999998"
                },
                {
                    "name": "permissionCode",
                    "valueCoding": {
                        "system": "https://fhir.nhs.uk/CodeSystem/SCR-ACSPermission",
                        "code": "Ask"
                    }
                }
            ]
        }
    ]
}

Example setPermission success response

Returns an operationOutcome on sucess or failure

HTTP/1.1 201 Created
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "OperationOutcome",
  "id": "27242108-f2ee-429c-a387-ace44bb87f40",
  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "details": {
        "text": "Resource Created"
      }
    }
  ]
}

Example setPermission failure response

Returns an operationOutcome on failure. Error handling is in line with Spine Error Codes II [NB: internal Confluence link].

HTTP/1.1 400 Bad Request
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "OperationOutcome",
  "id": "27242108-f2ee-429c-a387-ace44bb87f40",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Bad Request"
      }
    }
  ]
}

Post Alert

The SCR API provides a create operation, Post Alert, to allow GP Systems to record TMS Event Service (TES) Alerts centrally.

Endpoint
https://[baseURL]/AuditEvent
Query
POST https://[baseUrl]/AuditEvent 
Payload
SCR-Alert-AuditEvent 

Post Alert sequence diagram

AuditEvent

Example Post Alert call

POST https://[baseUrl]/AuditEvent /HTTP/1

Example Post Alert call payload

{
    "resourceType": "AuditEvent",
    "id": "example",
    "extension":  [
        {
            "url": "https://fhir.nhs.uk/StructureDefinition/Extension-SCR-NotificationMessage",
            "valueString": "Alert: Permission to view override 1C03CF4F-D404-4D76-B192-4F81727059F6"
        }
    ],
    "type": {
        "system": "https://fhir.nhs.uk/CodeSystem/SCR-AlertType",
        "code": "1",
        "display": "Create LR (Self Claimed)"
    },
    "subtype":  [
        {
            "system": "https://fhir.nhs.uk/CodeSystem/SCR-AlertReason",
            "code": "1",
            "display": "Access made in the public interest"
        }
    ],
    "recorded": "2020-11-13T00:00:00+00:00",
    "agent":  [
        {
            "who": {
                "identifier": {
                    "system": "https://fhir.nhs.uk/Id/nhs-number",
                    "value": "9999999998"
                }
            },
            "requestor": false
        },
        {
            "who": {
                "identifier": {
                    "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                    "value": "T10101"
                }
            },
            "requestor": false
        },
        {
            "role":  [
                {
                    "text": "General Practitioner"
                }
            ],
            "who": {
                "identifier": {
                    "system": "https://fhir.nhs.uk/Id/sds-user-id",
                    "value": "T10101"
                }
            },
            "requestor": false
        }
    ],
    "source": {
        "observer": {
            "identifier": {
                "system": "https://fhir.nhs.uk/Id/nhsSpineASID",
                "value": "227319907548"
            }
        }
    },
    "entity":  [
        {
            "what": {
                "identifier": {
                    "value": "1C03CF4F-D404-4D76-B192-4F81727059F6"
                }
            }
        }
    ]
}

Example Post Alert success response

Returns a minimal response, i.e. just the successful http status, on successful write to the repository.

HTTP/1.1 201 Created
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json

Example Post Alert failure response

Returns an operationOutcome on failure. Error handling is in line with Spine Error Codes II [NB: internal Confluence link].

HTTP/1.1 400 Bad Request
Date: Tue, 24 Aug 2020 11:00:00 GMT
Content-Type: application/fhir+json
{
  "resourceType": "OperationOutcome",
  "id": "27242108-f2ee-429c-a387-ace44bb87f40",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Bad Request"
      }
    }
  ]
}