Pre-approved Messaging

Overview

Instantly sends documents and messages from an integrated partner system directly into the patient record. The responsible practitioner reviews the content and can then add it to the record. If the message isn’t received or an issue arises, the system defaults to the Document Review & Import method for further review and integration.

Benefits

  • Speed & Efficiency: Instantly integrates generated documents into the patient record, saving time and reducing administrative overhead.
  • Security & Integrity: Automatically scans all incoming documents for viruses and ensure document integrity.
  • Accountability & Transparency: users can track the status of messages to confirm successful transmission and integration.
  • Reduced Manual Processes: Eliminates the need for multiple reviews, making it ideal for routine patient information updates.
  • Fallback for Reliability: If the message isn’t received, the system defaults to the Document Review & Import method, ensuring no documents are missed.

Requirements

  • Sending systems must provide the organisation code for the recipient organisations, such as an Organisation Data Service (ODS) code.
  • Partner system must provide an authorisation code for user authentication, enabling document delivery to patient records via Toolbar Application.
  • Users must be log in via the toolbar, otherwise, messages revert to standard Patient Document Review & Import Method and can be assessed by any practice user for patient record inclusion.
  • Users must ensure only trusted and safe documents are submitted. If a content-related error response is received, the attachment must not be resent.
  • Users must review all generated documents before they are added to the patient’s record.
Note

This feature is only useable if the user has explicitly permitted it and Exchanged an Authorisation the Code. If permission is revoked by the user, the request will return a HTTP Error Response status code.

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 is 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 Pre-Authorization: Exchanging the Authorization the Code connects the application to the integrated partner system, allowing the practitioner to add patient information directly to the record without multiple reviews.
  • 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:

  • User: The healthcare professional performing the action.
  • Your System: Your system for generating patient data.
  • The Application: The Toolbar Application.
  • GP System: The recipient system.

Scenario:
A user completes a patient-related task in your system (e.g. a remote assessment or submission). Your system generates one or more documents, such as a PDF summary and optional images (JPEG or PNG), which need to be added to the patient’s record in the GP system.

Business Purpose:
To ensure instant transfer of clinical documents, enabling GPs to view relevant information and provide follow-up care without delay or duplicate data entry.

Preconditions:

  • The user is authenticated and authorised to send pre-approved patient data.
  • 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 does not exceed 10 and each file is under 5MB.

User Action:
The user previews the generated files and confirms that they should submitted to the patient’s record.
System Action:
Sends the files via the Application in a single message using the instant message access token.
Outcome:
If the GP system supports automatic import, the files are added to the 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:

  • User: The healthcare professional performing the action.
  • Your System: Your system for generating patient data.
  • The Application: The Toolbar Application.
  • GP System: The recipient system.

Scenario:
After completing a clinical activity, your system generates consultation notes that summarise the interaction. These notes must be sent to the GP system and recorded by the patient’s record in the GP system.
Business Purpose:
Support instant transfer of safe and accurate documentation of clinical encounters, ensuring the GP system has access to current, structured information about the patient's care.
Preconditions:

  • The user is authenticated and authorised to send pre-approved patient data.
  • The Application is active and configured on your system.
  • The patient’s NHS number and GP system details are available.
  • Your system has generated valid consultation notes for preview.
  • The notes meet content and size limits for message attachments.

User Action:
The user previews and confirms the notes for submission to the patient’s record.

System Action:
Sends the consultation notes using the instant message access token.

Outcome:
If supported by the GP system, notes are imported as searchable, structured text; if not, they are stored as plain text file attachments.

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:

  • User: The healthcare professional performing the action.
  • Your System: Your system for generating patient data.
  • The Application: The Toolbar Application.
  • GP System: The recipient system

Scenario:
A patient interaction generates both consultation notes and SNOMED-coded clinical data. These need to be sent together to the GP and added to the patient’s record in the GP system.

Business Purpose:
Improve clinical documentation and coding through the instant delivery of structured SNOMED data alongside narrative notes, enabling audit, reporting, and decision support where supported.

Preconditions:

  • The user is authenticated and authorised to send pre-approved patient data.
  • 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:
Sends the SNOMED-coded data with a consultation summary notes using the instant message access token.

System Action:
The user previews the consultation notes and SNOMED data, then confirms they should be submitted to the patient’s record.

Outcome:
If supported by the GP system, SNOMED-coded data is imported as searchable, structured text; if not, only the notes are stored.

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

HTTP Request

Method: POST
End Point: /messages/Instant

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.
Conneqt-Instant-Access-Token An Instant Access Token obtained and verified by the Pre-approved Messaging Integration Guide.

Request Body

{
    "messageId": "5fd06ef9-8dfd-41de-af35-0d499fdac876",
    "type": "ToolbarInstantMessage",
    "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"
        }
    ],
}

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 "ToolbarInstantMessage" string Yes "ToolbarInstantMessage"
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, a default expiry will be used. The date and time must be 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 Infomation will be in visable 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": "about:blank",
  "title": "Service Unavailable",
  "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
Patient Document Review & Import Integration Guide
GP Connect Routing Integration Guide

Referenced Pages

Getting Started
Instant Messaging Access Endpoints
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
Instant Messaging Access Tokens
Obtataing an Instant Access Token
Verifying an Instant Access Token

External Resources
Organisation Data Service (ODS)
SNOMED data
Windows file name conventions

For More Help

Please don't hesitate to Contact Us for assistance