Polling API Manual

The Retarus Fax Inbound API allows you to actively retrieve faxes from your Retarus cloud-based infrastructure, rather than waiting for them to be pushed to your web service.

How it works

Organizing
You organize faxes by topics—identifiers configured in the EAS portal that group related inbound telephone numbers.
Polling
You make requests to retrieve fax metadata and document URLs for a specific topic.
Processing
You download and process the fax documents.
Acknowledging
You acknowledge receipt to remove faxes from future responses.

Key concepts

Job lifecycle

Unacknowledged jobs
New faxes appear in API responses until acknowledged.
Timeout
Each retrieved job has a timeout (default: 60 seconds) preventing it from appearing in other requests.
Acknowledgment
Once acknowledged, a job is permanently removed and will never appear again.
Automatic cleanup
Documents are deleted after 7 days regardless of download or acknowledgment status.

Polling behavior

Returns up to the number of faxes specified by the fetch parameter.
Faxes are returned in approximate order of receipt.
Only unacknowledged jobs without active timeouts are returned.
Calling next or exit URLs automatically acknowledges all jobs from that response.

Response structure

All API requests and responses are JSON serialized and encoded using UTF-8. Each API response contains:

Meta section: Request information and URLs for next actions.
Results section: Fax job metadata and document download URLs.

Version

Version: v1.0

URI scheme

Host	`api.us1.retarus.com` `api.us2.retarus.com` `api.de1.retarus.com` `api.de2.retarus.com` `api.sg1.retarus.com` `api.ch1.retarus.com`
Base path	`/faxin/rest/v1`
Schemes	HTTPS

📌 Correct URL
Your implementation engineer will provide the correct URL for your configuration.

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 client successfully retrieved the previous jobs through the ids parameter. This acknowledges the jobs.

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 below) 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 - Inbound 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