Polling API Manual

Retarus Fax Inbound API allows clients to actively retrieve faxes received for you via the Retarus cloud-based infrastructure instead of passively waiting for them to be delivered to a web service.

The main REST resource (the inbound fax) names a topic, i.e., a string of characters configured in the EAS portal and used to identify a set of inbound telephone numbers which need to be retrieved together.

For each topic, the API provides the metadata for received faxes, including the URL to the fax documents itself.

Every inbound document is made available once and then hidden. However, fax receipt should be acknowledged by the client in the subsequent retrieval. If this doesn’t happen within a pre-defined timeout period, the document is made available again, assuming that there was some issue with the application in retreiving it.

Each request or response in this document is JSON serialized and encoded using the UTF-8 character set.

The faxes are presented in the approximate order in which they were received, with no guarantee of an exact sequence.

Documents are automatically deleted 7 days after receipt, regardless of whether they were downloaded.

Version

Version: v1.0

URI scheme

Security

basicAuth

Each HTTP request to the Webservice must be authenticated via Basic Authorization using the following format and encoded via Base64:
<Retarus Customer Number>:<Password>

Example:
Authorization: Basic OTk5OTk6S0tkUVNHSU1XME1mOTdiVA==

The passwords are provided by Retarus and they can be associated to one or more incoming telephone numbers. Multiple processes can be operated concurrently by the Webservice using the same password or multiple passwords.

Type: basic

Paths

Getting new faxes for a specific topic

NONE

POST /topics/{topic}

Description

You retrieve new faxes for a topic via a POST request to the corresponding URL. The response consists of two parts: meta and results.

The meta part contains information about the request and two URLs that the client should call after retrieving the jobs, the next URL, or the exit URL.

The next URL is used to retrieve an additional batch of faxes if available. The request also confirms that the previous jobs were successfully retrieved by the client through the ids parameter.

The exit URL is just another call to the same URL with the fetch parameter set to 0. It is used to confirm the reception of the previous jobs without retrieving any new ones, for example, in case a shutdown of the client is requested.

The response to the next and exit URLs has the identical structure and function as the ones described here.

The results part contains information about the available fax jobs. This includes both the metadata of the transmission and the URLs from which the client can retrieve the fax images.

Parameters

Type	Name	Description	Schema
Path	topic required	The topic to be polled.	string
Query	fetch required	The number of results that the client requests.	integer
Query	ids optional	IDs of faxes that were acknowledged in this request. It must be comma-separated and presented in URL encoding, e.g. 365%2C366%2C367%2C368.	< integer > array(csv)
Query	timeout optional	Lock timeout in seconds for a fax (by default 60). Once the metadata for a fax has been provided to a client, it will be marked as "locked" and not be returned again in subsequent requests. If the timeout expires without the client having acknowledged the correct receipt, the server will assume that a problem has occurred and it will make the fax available again in the next response.	integer

Responses

HTTP code	Description	Schema
200	OK	ResponseObject
401	Authentication information is missing or invalid Headers: `WWW_Authenticate (string)`	No content

Produces

application/json

Example HTTP response

Response 200

JSON

{
   "meta":{
      "version":1,
      "next":"https://api.us1.retarus.com/faxin/rest/v1/topics/jhk234509sdfD?fetch=10&timeout=60&id
s=29%2C30",
      "exit":"https://api.us1.retarus.com/faxin/rest/v1/topics/jhk234509sdfD?fetch=0&timeout=60&ids
=29%2C30",
      "topic":"jhk234509sdfD",
      "resultSize":2,
      "parameters":{
         "fetch":10,
         "timeout":60,
         "ids":[ ]
      }
   },
   "results":[ {
         "id":"29",
         "callId":"J5WA4IAA@BXATD0S.glagqaseq108.DC2",
         "costCenter":"my billing code",
         "dateReceived":"2017-08-03T12:09:13+0200",
         "totalDuration":23,
         "senderIsdn":"00498912345678",
         "senderFaxId":"Retarus/Doe",
         "receiverIsdn":"+4989262080440",
         "receiverFaxId":"Retarus Faxolution",
         "faxResolution":"HIGH",
         "faxBaudRate":33600,
         "faxPageCount":1,
         "faxClassicStatus":"OK",
         "faxNumericStatus":"2.0.0",
         "archivingStatus":"NOT_CONFIGURED",
         "archiveExpiry":"",
         "documents":[ {
               "type":"image/tiff",
               "url":"https://api.us1.retarus.com/faxin/rest/v1/files/20.tif"
            } ]
      },
      {
         "id":"30",
         "callId":"J5WA55PT@CXEFXVG.glagqaseq109.DC2",
         "costCenter":"my billing code",
         "dateReceived":"2017-08-03T12:09:43+0200",
         "totalDuration":42,
         "senderIsdn":"00498912345678",
         "senderFaxId":"Retarus/Doe",
         "receiverIsdn":"+4989262080440",
         "receiverFaxId":"Retarus Faxolution",
         "faxResolution":"HIGH",
         "faxBaudRate":26400,
         "faxPageCount":1,
         "faxClassicStatus":"OK",
         "faxNumericStatus":"2.0.0",
         "archivingStatus":"NOT_CONFIGURED",
         "archiveExpiry":"",
         "documents":[ {
               "type":"application/pdf",
               "url":"https://api.us1.retarus.com/faxin/rest/v1/files/21.pdf"
            } ]
      } ]
}

Definitions

FaxJobObject

Name	Description	Schema
archiveExpiry optional	If the archiving status (see directly above) is NOT_CONFIGURED or FAILED, this will be an empty string, otherwise the string will contain the following format: `yyyy.MM.dd`.	string
archivingStatus optional	Archiving state. Possible values are listed below: NOT_CONFIGURED - Archiving not configured SUCCEEDED - Archiving succeeded FAILED - Archiving failed RUNNING - not completed within the wait time	enum (NOT_CONFIGURED, SUCCEEDED, FAILED, RUNNING)
callId optional	ID of the call where this fax was received in. Also used in tracking or reporting.	string
costCenter optional	Billing code.	string
dateReceived optional	Start date and time of the phone call.	string (dateTime)
documents optional	The fax document file(s). Normally there is only one document, but if Optical Character Recognition is used, there can be multiple documents since Retarus OCR service allows multiple output formats.	<ImageObject> array
faxBaudRate optional	The fax baud rate.	integer
faxClassicStatus optional	The status of the fax transmission. For details, see Transmission status codes - Outbound Fax.	string
faxNumericStatus optional	Numerical status of the fax transmission (more detailed than classicStatus).	string
faxPageCount optional	The total number of pages in the fax job.	integer
faxResolution optional	The resolution of the fax. Options are HIGH (200x200), LOW (200x100), MIXED (in case the document contains a combination of HIGH and LOW pages).	string
id optional	ID used in the next URL to acknowledge the receipt of this fax.	string
receiverFaxId optional	The recipient’s Fax ID.	string
receiverIsdn optional	The recipient’s ISDN number in E.164 format.	string
senderFaxId optional	The sender’s Fax ID.	string
senderIsdn optional	The sender’s ISDN number in E.164 format.	string
totalDuration optional	Length of the phone call of the fax transmission (in seconds).	integer

ImageObject

Describes an image and the information to retrieve it.

Name	Description	Schema
type required	MIME type of the available image.	enum (application/json, image/tiff)
url required	The URL from which the image should be retrieved. Documents are automatically deleted 7 days after receipt, regardless of whether they were downloaded.	string

MetadataObject

Provides meta-information about the request.

Name	Description	Schema
exit optional	The URL used to confirm that previous fax(es) have been correctly received and that no further faxes should be returned.	string
next optional	The URL used to request the next faxes and confirm that previous fax(es) have been correctly received.	string
parameters optional		StatusObject
resultSize optional	The number of elements contained in in the results array.	integer
topic optional	Name of the topic contained in the next request. Is contained in the URL (denoted by <topic>).	string
version optional	The API version number (will always be "1").	integer
meta required		MetadataObject
results required	Contains the metadata for the received faxes.	<FaxJobObject> array

ResponseObject

Name	Description	Schema
meta required		MetadataObject
results required	Contains the metadata for the received faxes.	<FaxJobObject> array

StatusObject

The actual parameters used for the request with source from defaults and URL parameters. It may
differ from URL parameters if the ones provided by the client are invalid.

Name	Description	Schema
fetch optional	The maximum number of faxes to be included in one response.	integer
ids optional	ID used in the next URL to acknowledge the receipt of this fax. See the query parameter description for more details.	<integer> array
timeout optional	The maximum number of seconds until receipt of the current fax is expected to be acknowledged. See the query parameter description for more details.	integer