Send Message

Description

This endpoint is utilized for sending documents to GP (General Practice) systems that are registered with the service. It serves as the gateway for transmitting various types of documents, such as patient records, consultation notes, and other medical information, to the designated GP systems. This ensures seamless and secure communication between healthcare providers and GP practices, facilitating the exchange of essential healthcare data.

Message expiry

It's essential to keep in mind that messages sent through the transfer service are not stored indefinitely. The service does not serve as a long-term message status repository. Message statuses will be accessible until their specified expiration date. However, after this date, the message may be removed from the system, and you should not rely on its status being available for retrieval. This ensures efficient use of system resources and data management practices.

Permitted attachment types

The service supports the following content types for attachments:

  • PDF (application/pdf): Documents in Portable Document Format.
  • JPEG (image/jpeg): Images in JPEG format.
  • Plain Text (text/plain): Unformatted text content.
  • Consultation Notes (text/vnd.qxlva.conneqt.consultation): Custom-defined content type used to carry plain text consultation notes.

Consultation Notes

Attachments defined as the 'Consultation Notes' MIME type ('text/vnd.qxlva.conneqt.consultation') will be applied to the patient record as user-searchable text, rather than as a file upload. Therefore, the content of attachments of this type must be in plain text format. The exact way this text appears in the patient record may vary depending on the GP System.

The transport process for attachments of this type via the API is otherwise identical to other attachment types. The content is included in the API message as a Base64 encoded block along with a filename.

Attachment size limit

There is a 5MB size limit for each attachment. This limit is set by the receiving GP systems and applies to each individual attachment.

Allowed number of attachments

You can include a maximum of 10 attachments in a single message.

HTTP Definition

Method: POST
Endpoint URL: /api/v1/messages

Headers

The following HTTP headers are required with this request:

Name Data Type Notes
ApiKey string The unique key issued by Quicksilva to identify your system.
Content-Type string Must define the request content as 'application/json'.

URL Parameters

The request contains no URL parameters.

Request JSON Definition

Name Cardinality Data Type Notes
messageId 1..1 uuid A unique identifier for this specific message instance.
topic 1..1 string A system-defined category used to classify this message.
recipient 1..1 object The intended recipient of this message.
recipient.id 1..1 object An object containing identification data for the recipient.
recipient.id.type 1..1 string A string indicating the type of recipient ID being used.
recipient.id.value 1..1 string The value of the recipient ID, such as an organisation's ODS code.
subject 1..1 object The subject (i.e. patient) of this message
subject.id 1..1 object An object containing identification data for the subject.
subject.id.type 1..1 string Specifies the type of subject ID being used, like "VerifiedNhsNumber."
subject.id.value 1..1 string The value of the subject ID being used, such as a patient's verified NHS number.
expiryDateTime 0..1 date-time The date and time when the message will expire, and it will no longer be eligible for delivery. Use a full RFC3339 timestamp with 'Z' or offset. It should be set in the future.
body 0..1 object Free-text information that will be displayed to the message recipient, if needed.
body.mimeType 1..1 string Specifies the type of content being conveyed, influencing its presentation.
body.content 1..1 string The textual representation of the message's body content.
attachments 1..10 array An array containing one or more (max 10) file attachments to be included with the message sent to the recipient.
attachments[0].mimeType 1..1 string Denotes the type of attachment being included in the message. See Permitted attachment types for allowed MIME types.
attachments[0].fileName 1..1 string The name of the file represented by the attachment. The file name provided may appear in recipient systems where supported. File name must be a valid Windows file name following the rules given here https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions, and may not have leading and/or trailing whitespace or periods.
attachments[0].content 1..1 string The content of the attachment, encoded in Base64.
codedDataItems 0..* array Optional SNOMED Coded Data Items; a list of SNOMED coded data items representing the content of the attachment included in this message.
codedDataItems[0].code 1..1 string The specific SNOMED code.
codedDataItems[0].value 0..1 number A value associated with the SNOMED code, if applicable.
codedDataItems[0].unit 0..1 string Units of measurement associated with the value, if applicable.
codedDataItems[0].additionalText 0..1 string Additional descriptive free text linked to the code. 
POST https://int.conneqt.health/api/v1/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
ApiKey: <API-KEY-PLACEHOLDER>

{
  "messageId": "869c3439-fcb8-4546-b372-2af2bf54e197",
  "topic": "DispenseEventNotification",
  "recipient": {
    "id": {
      "value": "GPPRAC001",
      "type": "OcsClientIdentifier"
    }
  },
  "subject": {
    "id": {
      "value": "9547852140",
      "type": "VerifiedNhsNumber"
    }
  },
  "body": {
    "mimeType": "text/plain",
    "fileName": "Dispense Notification.pdf",
    "content": "Dispense Event Notification: Copy of prescription form in attached PDF"
  },
  "attachments": [
    {
      "mimeType": "application/pdf",
      "content": "QW4gZXhhbXBsZSBvZiBhIHBheWxvYWQgYmVpbmcgZW5jb2RlZCBmb3IgdHJhbnNmZXIKVGhpcyBpcyBhIHNpbXBsZSB0ZXh0IHBheW"
    }
  ],
  "codedDataItems": [
    {
      "code": "407554009",
      "value": 140,
      "units": "mmHg",
      "additionalText": "Sitting systolic blood pressure"
    },
    {
      "code": "407555005",
      "value": 80,
      "units": "mmHg",
      "additionalText": "Sitting diastolic blood pressure"
    },
    {
      "code": "248223005",
      "additionalText": "Feeling faint"
    }
  ]
}
Note

The example attachment content provided is truncated and should not be considered a valid Base64-encoded PDF file.

Response JSON Definition

Name Cardinality Data Type Notes
messageStatusEndpoint 1..1 url The endpoint location to obtain delivery status data for the sent message 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "messageStatusEndpoint": "/api/v1/messages/869c3439-fcb8-4546-b372-2af2bf54e197/status"
}

Error Responses

If there was an issue processing your request, a HTTP error response will be returned, containing details of the issue. Common problems include:

  • One or more invalid data items were found in the request.
  • The intended recipient organisation is not one that uses our system.

The system uses the definition of an IETF Problem, as described in RFC 7807, in error responses to provide machine-readable details of why a request was rejected. The content of the Problem returned depends on the nature of the issue.

HTTP Response Code HTTP Reason Code Description
400 Bad Request Validation issues found in your request.
401 Unauthorized Missing or Invalid API Key in the Request Header.
403 Forbidden Unauthorized Client System - The Provided API Key Is Valid but Not Authorized.
500 Internal Server Error Internal Server Error - An Internal Server Error Prevented the Request from Being Processed. 
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https//qxlva.com/im1toolbar/documentation/api/v1/validation-error",
  "title": "Request Validation Error",
  "status": 400,
  "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000",
  "invalidParameters": [
    {
      "name": "recipient",
      "reason": "Unknown Recipient"
    },
    {
      "name": "body.mimeType",
      "reason": "Must be 'text/plain' or 'text/html'",
      "value": "application/pdf"
    }
  ]
}

See Also