Query Message Status

Description

This is the endpoint used to query the current status of a given message.

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.

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/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 0..1 string Only used for instant messages to provide detail on why the instant message was not imported.
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

The status field will carry one of the following values:

Status Description
PENDING Message accepted and is awaiting processing by recipient
COMPLETED Attached document imported into patient record
REJECTED Message rejected by recipient
FAILED Message failed to be imported into patient record
EXPIRED Message expired before being downloaded by recipient

Sub-Status

The subStatus field may be present in response to a query for a message sent via instant messaging when the message has expired or failed, and carries a text description of the reason for the state change.

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