Patient Document Review & Import

Overview

Send various document types (i.e. PDFs, images, text, SNOMED data) to a recipient organisation, such as a GP Practice, for review. A recipient can accept or reject the documents for inclusion in the patient’s record. Accepted documents are then integrated into the record. The system tracks the status of each document, ensuring transparency and accountability. Note that SNOMED data can only be added if accompanied by one or more files that represent coded clinical concepts from those files. This review process also acts as a fallback if Pre-approved Messaging fails.

Benefits

  • Security & Integrity: Automatically scans all incoming documents for viruses and ensure document integrity.
  • Accountability & Transparency: Tracks the status of each document to ensure clear audit trails and accountability.
  • Support for Multiple Document Types: Supports PDFs, images, text files, and SNOMED data.
  • Review & Quality Control: Provides a manual review process for documents before integration into the patient record.
  • Fallback Mechanism: If Pre-approved Messaging fails, this method ensures documents are still processed and integrated.

Requirements

  • Sending systems must provide the organisation code for the recipient organisations, such as an Organisation Data Service (ODS) code.
  • Sending systems must provide a verified patient NHS number.
  • Users must ensure only trusted and safe documents are submitted. If a content-related error response is received, the attachment must not be resent.

Getting Started

Requirements

  • Requested & set up the SDK: This can be requested by filling out our form on the Welcome Page and following the guide on Getting started with the SDK.
  • Access to Test Patient Administration System (PAS): Instructions on accessing the Test PAS are included in the guide on Getting started with the SDK.
  • Obtain Identifiers: The API key and the OCS code are in the connection details.txt included with the SDK during testing.
  • Obtain verified NHS number of the patient: This is provided in the PAS Patients JSON File during testing.
  • Obtain a topic: Located in the GET topics request . This is needed to categorise the type of message being sent.
  • A file for the patient’s record: All requests must include 1 to 10 attachments, each under 5MB.
Note

The file type must be one of the supported formats and cannot exceed 5MB. The Multipurpose Internet Mail Extensions (MIME) protocol is used for handling file content during transmission.
Supported MIME attachment types:

1. Plain Text [text/plain]: Unformatted text.
2. PDF [application/pdf]: Portable Document Format is an Adobe-developed file format that ensures consistent document presentation across various operating systems and software.
3. PNG [image/png]: Portable Network Graphic file is a type of lossless raster image file.
4. JPEG [image/jpeg]: a standard file format for storing digital images.
5. Consultation Notes [text/vnd.qxlva.conneqt.consultation]: Custom content type for plain text consultation notes.

Following-up

Once you complete the request, you will be able to:

  • Review & Import the document into the patient record from the Toolbar Application.
  • Query the Message Status from our API end-point.

Use Cases

Send One or More Documents to the Patient’s GP

Actors:

  • Patient: A person seeking medical treatment or care from a healthcare professional.
  • User: The healthcare professional performing the action.
  • Your System: Your system for generating patient data.
  • The Application: The Toolbar Application.
  • Primary Care Physician: A healthcare professional serving as the main contact for medical issues and coordinating referrals to specialists for the patient.
  • GP System: The recipient system used by the primary care physician.

Scenario:
A patient has interacted with the user by participating in a remote consultation, completing a health assessment, or submitting clinical information. As a result of this interaction, your system has produced one or more documents, such as a consultation summary, image, or form, which must be added to the patient's record in GP system.

Business Purpose:
Ensure the Primary care physician is kept informed of clinical activity occurring outside the practice. This supports safe, joined-up care and allows the GP system to maintain a complete and accurate patient record.

Preconditions:

  • The Application is active and configured on your system.
  • The patient’s NHS number and GP system details are available.
  • Your system has successfully generated one or more supported files (PDF, JPEG, PNG).
  • The total number of attachments is between 1 and 10, with each file under 5MB.

User Action:
The user previews the generated files and confirms they should be submitted to the primary care physician for inclusion in the patient’s record.

System Action:
Sends the files via the Application in a single message to the GP System.

Outcome:
The Primary care physician reviews the documents and chooses whether to add them to the GP systems patient's record.

Check our guide on Sending One or Multiple Documents, for more details.

Send Consultation Notes as Structured Text or File Attachment

Actors:

  • Patient: A person seeking medical treatment or care from a healthcare professional.
  • User: The healthcare professional performing the action.
  • Your System: Your system for generating patient data.
  • The Application: The Toolbar Application.
  • Primary Care Physician: A healthcare professional serving as the main contact for medical issues and coordinating referrals to specialists for the patient.
  • GP system: The recipient system used by the primary care physician.

Scenario:
Your system has recorded structured consultation notes summarising a patient interaction. These notes need to be shared with the patient’s Primary care physician for inclusion in their GP system's patient's record.

Business Purpose:
Ensure the primary care physician has access to structured, relevant clinical data, supporting accurate and searchable patient records.

Preconditions:

  • The Application is active and configured on your system.
  • The patient’s NHS number and GP system details are available.
  • Your system has generated structured, searchable text supported by the receiving system, or a plain text file attachment if structured text is not supported.
  • The notes meet content and size limits for message attachments.

User Action:
Reviews and submit the notes to the primary care physician.

System Action:
Sends the consultation notes to the GP system.

Outcome:
Primary care physician reviews the consultation notes and determines whether to add them into the GP system's patient's record.

Check our guide on Sending Consultation Notes as Structured Text or File Attachment, for more details.

Send SNOMED-Coded Data with a Consultation Summary

Actors:

  • Patient: A person seeking medical treatment or care from a healthcare professional.
  • User: The Healthcare professional performing the action.
  • Your System: Your system for generating patient data.
  • The Application: The Toolbar Application.
  • Primary Care Chysician: A healthcare professional serving as the main contact for medical issues and coordinating referrals to specialists for the patient.
  • GP system: The recipient system used by the primary care physician.

Scenario:
Following a patient interaction, the user generates consultation notes and SNOMED-coded clinical data from your system to share with the patient’s primary care physician.

Business Purpose:
Support structured clinical recording, interoperability, and the use of coded data for reporting or decision support within the GP’s system.

Preconditions:

  • The Application is active and configured on your system.
  • The patient’s NHS number and GP system details are available.
  • Your system has generated both valid consultation notes and accurate SNOMED codes.
  • A human-readable version of the SNOMED data is available for the user to review.
  • SNOMED data is mapped appropriately by the GP system.
  • Files comply with attachment limits (number, size, type).

User Action:
Reviews and submits the consultation notes, and human-readable SNOMED data, to the primary care physician.

System Action:
Sends a human-readable consultation summary (e.g. a PDF) accompanied by SNOMED-coded data to the GP System.

Outcome:
The primary care physician reviews the consultation summary and coded data, and determines whether to add them into the GP system's patient's record.

Check our guide on Sending SNOMED-Coded Data with a Consultation Summary, for more details.

HTTP Request

Method: POST
End Point: /messages

Request Header

The following HTTP headers are required with this request:

Name Description
Content-Type Set to "application/json"; content-type identifies media type.
ApiKey A unique key issued alongside the Toolbar SDK used to identify your system.

Request Body

{
    "messageId": "5fd06ef9-8dfd-41de-af35-0d499fdac876",
    "type": "ToolbarMessage",
    "topic": "Health",
    "recipient": {
        "id": {
            "value": "G00001",
            "type": "OcsClientIdentifier"
        }
    },
    "subject": {
        "id": {
            "value": "4857773456",
            "type": "VerifiedNhsNumber"
        }
    },
    "expiryDateTime": "2025-07-21T17:32:28+01:00",
    "body": {
        "mimeType": "text/plain",
        "content": "Dispense notification for SMITH, John"
    },
    "attachments": 
    [
        {
            "fileName": "document.pdf",
            "mimeType": "application/pdf",
            "content": "YmFzZTY0ZW5jb2RlZHN0cmluZw=="
        }
    ],
    "codedDataItems": [
        {
        "code": "399304008",
        "value": 140,
        "units": "mmHg",
        "additionalText": "Sitting systolic blood pressure at consultation."
        }
    ],
}

Parameter Definition Table

Parameter Name Description Type Required Example
messageId The unique identifier for the message, generated by the sender. UUID Yes "5fd06ef9-8dfd-41de-af35-0d499fdac876"
type The messaging feature used. This must be set to "ToolbarMessage". string No "ToolbarMessage"
topic The chosen topic from the GET topics request. string Yes "Health"
recipient The recipient object that encapsulates the details of the recipient. object Yes See nested table below.
subject The subject object that encapsulates the patient's details. object Yes See nested table below.
expiryDateTime The expiration Date and Time for message delivery in RFC3339 format, including a 'Z' for UTC or an offset (e.g., +01:00). If omitted, documents are defaulted to a 7-day delivery window, but this can be customised from 1 to 28 days in the future. DateTime No "2025-07-21T17:32:28+01:00"
body The body of the message encompassing both type and content. object Yes See nested table below.
attachments An array of 1 to 10 attachment objects. array Yes See nested table below.
codedDataItems An array of codedDataItems objects. array No See nested table below.

recipient:

Parameter Name Description Type Required Example
id.value The OCS Identifier given by the toolbar identify the recipient. string Yes "G00001"
id.type The recipient's identifier type. This must be set to "OcsClientIdentifier". string No "OcsClientIdentifier"

subject:

Parameter Name Description Type Required Example
id.value The authenticated NHS number of the patient. string Yes "4857773456"
id.type The subject's identifier type. This must be set to "VerifiedNhsNumber" string No "VerifiedNhsNumber"

body:

Parameter Name Description Type Required Example
mimeType Indicates the format of the content. This must be set to "text/plain". string Yes "text/plain"
content Contextual description for the recipient about the message content. This information will be in visible as a preview pf the message. string Yes "Dispense notification for SMITH, John."

attachments:

Parameter Name Description Type Required Example
fileName A file name that complies with Windows file name conventions, without leading or trailing whitespace or periods. This file name will be visible to client systems where supported. string Yes "document.pdf"
mimeType Multipurpose Internet Mail Extension, indicates the format of a file.
Supported MIME attachment types:

1. Plain Text [text/plain]: Unformatted text.
2. PDF [application/pdf]: Portable Document Format is an Adobe-developed file format that ensures consistent document presentation across various operating systems and software.
3. PNG [image/png]: Portable Network Graphic file is a type of lossless raster image file.
4. JPEG [image/jpeg]: a standard file format for storing digital images.
5. Consultation Notes [text/vnd.qxlva.conneqt.consultation]: Custom content type for plain text consultation notes.
 string Yes "application/pdf"
content Base64 encoded content of the attachment (max 5MB). string Yes "YmFzZTY0ZW5jb2RlZHN0cmluZw=="

codedDataItems:

Parameter Name Description Type Required Example
code The SNOMED code that aligns with NHS clinical terms for procedures, symptoms, measurements, diagnoses, and medications. string Yes "399304008"
value The value of the coded data item is optional unless required by the concept. It can include various medical values, such as the medication dose, or blood pressure readings (e.g., BP Systolic value). string No "140"
units field for units associated with the value. string No "mmHg"
additionalText Context for SNOMED item. string No "Sitting systolic blood pressure at consultation."

Responses

200 Success

{
  "messageStatusEndpoint": "/api/v1/message/947639e3-a7c9-4010-b0a9-931e828b9d21/status"
}

400 Bad Request

{
  "type": "https//qxlva.com/im1toolbar/documentation/api/v1/validation-error",
  "title": "Request Validation Error",
  "status": 400,
  "detail": "Invalid parameters",
  "instance": "22835b83-1050-49d2-9a46-ae71768150dc",
  "invalidParameters": [
    {
      "name": "recipient",
      "reason": "Unknown Recipient"
    },
    {
      "name": "body.mimeType",
      "reason": "Must be 'text/plain'",
      "value": "text/plain"
    }
  ]
}

401 Unauthorized

403 Forbidden. Supplied authorization material is valid, but access to this resource is forbidden.

406 Not Acceptable. Attachment failed virus scanning

{
  "type": "https://docs.quicksilva.info/toolbar/articles/error-types/api/v1/virus-scan-failed.html",
  "title": "Virus Scan Failed",
  "status": 503,
  "detail": "string",
  "instance": "string"
}

Please see The Error Type Descriptions for a complete list of errors.

See Also

OpenAPI 2.0 Specification

An OpenAPI 2.0 (Swagger) format specification for this API can be downloaded using the following link: conneQt® Platform Send Consultation OpenAPI Specification

Sending Documents Overview
Pre-approved Messaging Integration Guide
GP Connect Routing Integration Guide

Referenced Pages

Getting Started
Get Request Topics
PAS Patients JSON File
Query the Message Status
Software Development Kit

Use Cases
Sending A Document
Sending Consultation Notes as Structured Text or File Attachment
Sending Multiple Documents
Sending SNOMED-Coded Data with a Consultation Summary

HTTP Request
Authentication
Get Request Topics

External Resources
Organisation Data Service (ODS)
SNOMED CT data
Windows File Name Conventions

For More Help

Please don't hesitate to Contact Us for assistance