Send GP Connect Message
Description
This endpoint is used to send documents to utilize the NHS GP Connect Service to send consultation summary documents to a patient's GP Practice.
When using the message sending API to route via GP Connect, you'll need to include additional elements beyond the standard conneQt message API.
Permitted attachment types
GP Connect mandates that only a single document should be sent at a time, and that document must be a consultation summary in the specified format as detailed here.
Attachment size limit
There is a 5MB size limit for the attachment, this limit is mandated by the GP Connect service specification.
Allowed number of attachments
You must include exactly one attachment in a request message to this endpoint.
Send to MESH failures
GP Connect messages are delivered via the NHS MESH service. Send attempts are synchronous with the client's 'send message' action. Failures to send to the MESH service result in a 503 - Service unavailable response with a descriptive Problem Object, allowing for client retries.
HTTP Definition
Method: POST
Endpoint URL: /api/v1/gpconnect/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. |
| type | 1..1 | string | Fixed value that must be 'GPConnectMessage'. |
| 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, fixed as 'OdsOrganisationId'. |
| recipient.id.value | 1..1 | string | The recipient organisation's ODS code, if known. For GP Connect only, may indicate 'UNK' for unknown, or 'gpconnect' to indicate the service* |
| 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..1 | 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. |
| gpConnectAdditionalInformation | 1..1 | object | Additional metadata required for sending via GP Connect.. |
| gpConnectAdditionalInformation.recipientType | 1..1 | string | GP Connect intent, either 'For Action' or 'For Information'. |
| gpConnectAdditionalInformation.senderReference | 1..1 | string | Unique system reference to the consultation event, e.g. "Consultation-27542d94-26b3-4c2e-9056-5a951b659b60". |
| gpConnectAdditionalInformation.confidentiality | 1..1 | boolean | If the message is considered confidential in GP Connect terms. |
| gpConnectAdditionalInformation.relatesTo | 0..1 | string | When this message is to replace an earlier message, this shall be the identifier of the message being replaced. |
| gpConnectAdditionalInformation.versionNumber | 1..1 | integer | If message is a replacement for an earlier message, an incrementing version number indicating number of replacement. Must be greater than 1 for replacement sends, 1 otherwise. |
| gpConnectAdditionalInformation.patient | 1..1 | object | The patient subject. |
| gpConnectAdditionalInformation.patient.name | 1..1 | object | Patient Name object. |
| gpConnectAdditionalInformation.patient.name.family | 1..1 | string | Patient Family name. |
| gpConnectAdditionalInformation.patient.name.given | 0..1 | string | Patient Given name. |
| gpConnectAdditionalInformation.patient.dateOfBirth | 1..1 | string | Patient date of birth. |
| gpConnectAdditionalInformation.practitioner | 0..1 | object | Clinical Practitioner (author of summary). Must be provided if known. |
| gpConnectAdditionalInformation.practitioner.name | 1..1 | object | Clinical Practitioner (author) Name object. |
| gpConnectAdditionalInformation.practitioner.name.family | 1..1 | string | Practitioner Family name. |
| gpConnectAdditionalInformation.practitioner.name.given | 0..1 | string | Practitioner Given name. |
| gpConnectAdditionalInformation.practitioner.sdsUserId | 0..1 | string | SDS User ID of the practitioner. Must be provided if available. If not available, the client may specify the value 'UNK', or omit the element. In the event this element is omitted, the conneQt service will use the value UNK in the generated GP Connect message, in line with NHS Guidance. |
| gpConnectAdditionalInformation.practitioner.telephone | 0..1 | string | Work telephone of the practitioner, at least one of telephone or email should be specified if available. |
| gpConnectAdditionalInformation.practitioner.email | 0..1 | string | Work email of the practitioner, at least one of telephone or email should be specified if available. |
| gpConnectAdditionalInformation.organisation | 0..1 | object | Sending organisation details. |
| gpConnectAdditionalInformation.organisation.telephone | 0..1 | string | Organisation telephone, at least one of telephone or email should be specified if available. |
| gpConnectAdditionalInformation.organisation.email | 0..1 | string | Organisation email, at least one of telephone or email should be specified if available. |
| gpConnectAdditionalInformation.typeCode | 1..1 | string | SNOMED code for encounter type. |
| gpConnectAdditionalInformation.typeDescription | 1..1 | string | SNOMED display value for encounter type. |
Note
This endpoint requires the type field to be populated with the value "GPConnectMessage" to ensure your system has not sent a request intended for the standard messaging endpoint.
- The 'recipient ID' is required, but as the message is routed based on the subject (patient) details, you may, if the recipient ODS code is not known, instead set this to 'UNK' or 'gpconnect'.
POST https://int.conneqt.health/api/v1/gpconnect/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
ApiKey: <API-KEY-PLACEHOLDER>
AccessToken: ad2ae93e-f2e4-4722-8c20-42ba5a71b3ff
{
"messageId": "869c3439-fcb8-4546-b372-2af2bf54e197",
"type": "GPConnectMessage",
"topic": "DispenseEventNotification",
"recipient": {
"id": {
"value": "GPPRAC001",
"type": "OdsOrganisationId"
}
},
"subject": {
"id": {
"value": "9547852140",
"type": "NHSNumber"
}
},
"body": {
"mimeType": "text/plain",
"content": "Dispense Event Notification: Copy of prescription form in attached PDF"
},
"attachments": [
{
"mimeType": "application/pdf",
"fileName": "Dispense Notification.pdf",
"content": "QW4gZXhhbXBsZSBvZiBhIHBheWxvYWQgYmVpbmcgZW5jb2RlZCBmb3IgdHJhbnNmZXIKVGhpcyBpcyBhIHNpbXBsZSB0ZXh0IHBheW"
}
],
"gpConnectAdditionalInformation": {
"recipientType": "For Action",
"senderReference": "Consultation-27542d94-26b3-4c2e-9056-5a951b659b60",
"confidentiality": false,
"relatesTo": "8c7b1cb4-51ff-49f0-a2be-c7c5592e94f1",
"versionNumber": 1,
"patient": {
"name": {
"family": "Jones",
"given": "Henry"
},
"dateOfBirth": "1975-11-20"
},
"practitioner": {
"name": {
"family": "Jones",
"given": "Henry"
},
"sdsUserId": "153632348546",
"telephone": "01249 751000",
"email": "[email protected]"
},
"organisation": {
"telephone": "01249 751000",
"email": "[email protected]"
},
"typeCode": "325871000000103",
"typeDescription": "Remote consultation encounter type (record artifact)"
}
}
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/gpconnect/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. |
| 503 | Service Unavailable | Internal issues encountered communicating with the MESH service. |
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"
}
]
}