Query Message Status

Description

This is the endpoint used to query the current status of a given message that was sent via the conneQt Platform to a recipient using GP Connect.

Message expiry

It's essential to keep in mind that messages sent through the conneQt Platform 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.

Status retrieval frequency

Message status changes are dependent on human interactions at the target destination. Therefore, rapid message status polling is not necessary and should be avoided. Quicksilva reserves the right to rate-limit status requests.

We recommend the following behavior for retrieving message status:

  1. Infrequent polling: Poll no more than four times a day.
  2. "On user demand": Retrieve status when a client system event requires it, such as displaying it to a user or taking a business action.
  3. Immediately before the projected expiration if the terminal state has not been reached.

Please note that there is no need to retrieve further statuses for messages once they have reached a "terminal" state, which includes "REJECTED", "COMPLETED", or "EXPIRED." Once in these states, the message status will not change further.

HTTP Definition

Method: GET
Endpoint URL: /api/v1/gpconnect/messages/{message-id}/status

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.

URL Parameters

Name Cardinality Data Type Location Notes
message-id 1..1 uuid path The unique identifier for a message provided by your system in a Send Message request.

Request JSON Definition

This message does not include a request payload.

GET https://int.conneqt.health/api/v1/messages/869c3439-fcb8-4546-b372-2af2bf54e197/status HTTP/1.1
ApiKey: <API-KEY-PLACEHOLDER>

Response JSON Definition

Name Cardinality Data Type Notes
messageId 1..1 uuid The message id status pertains to.
status 1..1 string The status of the message.
subStatus 1..1 string The intermediary status of the message as it passes through the GP Connect message flow.
updated 1..1 timestamp The point in time the status was last updated. 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "messageId": "869c3439-fcb8-4546-b372-2af2bf54e197"
  "status: "PENDING"
  "subStatus" : "Acknowledged"
  "updated": "2022-04-27T12:42:38.649419+01:00"
}

Status and sub-status

The following table maps the status and subStatus field combinations that convery information pertinent to GP Connect:

Status Sub-status Description
PENDING Sent to MESH Message accepted and is awaiting acknowledgement of receipt by the recipient organisation.
PENDING 20013 - Success The document has been received by the recipient organisation (but not yet applied to the patient record).
COMPLETED {itk-response-code}-{itk-display-name} The document was imported into the recipient organisation patient record.
REJECTED {itk-response-code}-{itk-display-name} The document was rejected by the recipient organisation.
REJECTED {mesh-error-code}-{mesh-error-description} The document was rejected by the MESH infrastructure.
EXPIRED (null) The message could not be routed via MESH within the allotted time scale.

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.
404 Not Found Not Found - The Requested Message ID Was Not Found or Accessible.
500 Internal Server Error Internal Server Error - An Internal Server Error Prevented the Request from Being Processed.

See Also