Transaction API

Initiates a HTTP long poll on integration endpoint identified by iep. When establishing the connection the client should employ an idle timeout of at least 40 seconds and ensure that no proxy between the client and the API uses a more eager timeout.

GET /v3/igr/dub/{copid}/{iep}/receive?expire={download-url-expiry}&recid={recid} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}

The API will keep the HTTP connection open until at least one entity update becomes available for processing on the endpoint or until the wait timeout elapses. It then responds immediately, sending all accrued transactions over in the response body.

The response body may contain up to 10 transactions. The client is expected to process each transaction within the preconfigured processing timeout (typically 3 minutes) and acknowledge successful processing of each transaction by sending back a DELETE update request to the API.

The instantCMR API guarantees at-least-once delivery for each entity update. To ensure this, entity updates returned from GET unprocessed updates will be eventually returned again unless the client marks those updates as processed by sending a DELETE update request with the appropriate removal handle (rhnd) of the entity update.

The instantCMR API also guarantees in-order and exactly-once delivery for each entity update that is processed (and successfully marked as such) within the preconfigured processing timeout. To achieve this, entity updates returned to the client from GET unprocessed updates will be marked as inflight by the API for the duration of the preconfigured processing timeout. While an entity update is marked as inflight, neither the same entity update, nor any other entity update corresponding to the same (trip, document, or user) entity will be returned from subsequent GET unprocessed update requests. If the client does not mark the entity update as processed within the processing timeout, the update will go back to unprocessed state and become eligible for retrieval again.

If the client observes a network outage or temporary service outage (HTTP 429, HTTP 5XX) it should resend the same request after employing an exponential backoff. In this scenario the instantCMR API can only guarantee exactly-once delivery by keeping all entity updates that it previously returned to the original requestor as inflight and not returning them until the processing timeout elapses, effectively delaying those entity updates by several minutes. To avoid this, the client can decorate each GET unprocessed updates with a randomly generated receive identifier (recid) and resend the same receive identifier when it retries the same GET unprocessed updates request after a network error. The instantCMR API will return the same entity updates (even if they are inflight) to the client as long as it receives the same receive identifier as in the original request.

HTTP/1.1 200 Thank you  
Date: Fri, 24 Jan 2020 14:12:19 GMT  
Content-Type: application/json; charset=UTF-8  
Transfer-Encoding: chunked  

{  
    "rgdubm": [  
        {dubm1},  
        {dubm2},  
        …  

        {dubm10}  
     ]  

}  

Removes an entity update (previously received as a response to a GET unprocessed updates request) from the unprocessed entity update queue.

DELETE /v3/igr/dub/{copid}/{iep}/rhnd/{rhnd} HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 Thank you  
Date: Fri, 24 Jan 2020 15:42:01 GMT  
Content-Type: text/html; charset=UTF-8  
Content-Length: 0  

Downloads an image attached to a document.

Note, that images can receive updates as a result of reviewers manipulating images on the instantCMR Hub. Images can be reviewed (accepted or rejected), added to or removed from documents, or edited (cropped, rotated and adjusted). Such edits may or may not alter the binary representation of the attached image.

Document images are identified by the Dubdosuimg.imgid field, meaning that and document entity updates (Dubdosu) that contain updated data for the same attached image (such as a review, or edit) will contain a Dubdosuimg entity in its Dubdosu.rgimg field with the same imgid value.

If the binary content of an attached image has been changed, it will be signalled in the Dubdosuimg.odoed.doedid field. Hence the binary representation of attached images is guaranteed to stay identical if and only if both the document image identifier (Dubdosuimg.imgid) and the document edit identifier (Dubdoed.doedid) stays identical. These two identifiers combined identify the binary content of the attached image.

GET {image-url-path} HTTP/1.1  
Host: {image-url-host}  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 Thank you  
Content-Length: 67676  
Content-Type: image/jpeg  
Etag: "16049243cba368ad9bea03033d6f2fb6"  
Last-Modified: Thu, 23 Nov 2017 21:14:23 GMT  

{image-bytes}