Fax2WSPull (v0)

Fax2WSPull 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 unit of organization for this process is the topic. A topic represents one or more fax numbers that are used to receive faxes.

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

Every inbound document showed as available is hidden after retrieval. However, fax receipt should be acknowledged by the client in the retrieval process. 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 during the retrieval process.

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

The fax documents themselves are automatically deleted 7 days after receipt by default, regardless of whether they were downloaded or not.

Download OpenAPI description
fax2ws-pull-api.json
fax2ws-pull-api.yaml
Overview
URL https://www.retarus.com/
Retarus info@retarus.com
 Terms of Service
Languages
Servers
Mock server
https://developers.retarus.com/_mock/fax/fax2ws-pull-api/
Retarus data center in Frankfurt, Germany
https://api.de1.retarus.com/faxin/rest/v1/
Retarus data center in Munich, Germany
https://api.de2.retarus.com/faxin/rest/v1/
Retarus data center in Ashburn, United States
https://api.us1.retarus.com/faxin/rest/v1/
Retarus data center in Secaucus, United States
https://api.us2.retarus.com/faxin/rest/v1/
Retarus data center in Zurich, Switzerland
https://api.ch1.retarus.com/faxin/rest/v1/
Retarus data center in Singapore
https://api.sg1.retarus.com/faxin/rest/v1/

Fax2WSPull Client

Operations

Retrieve fax jobs from a topic and confirm the receipt.

Request

This endpoint is used for two types of processes:

On the one hand, you can retrieve a list of unlocked and non-acknowledged fax jobs from a topic owned by the authenticated user. The amount of fetched faxes is limited by the fetch parameter. On the other hand, you should acknowledge faxes that you successfully received by specifying an URL-encoded list of fax job ids.

You retrieve the list of available 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 retreiving the jobs, the next URL or the exit URL. Retrieving the faxes themselves is described in the GET operation below.

The next URL is used to retrieve an additional batch of available faxes. 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 retreiving information about 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 for the fax and the transmission and the URLs from which the client can retrieve the fax images.

Path
topicstringrequired

Topic to be polled

Example: abc123
Query
fetchinteger

Number of fax jobs requested by the customer to be fetched from the topic

Example: fetch=10
idsstring

List of fax job ids to be acknowledged in this request. It must be comma-separated and presented in URL encoding, e.g. 365%2C366%2C367%2C368.

Example: ids=365%2C366%2C367%2C368
timeoutinteger

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.

Default 60
curl -i -X POST \
  -u <username>:<password> \
  'https://developers.retarus.com/_mock/fax/fax2ws-pull-api/topics/{topic}?fetch=10&ids=365%252C366%252C367%252C368&timeout=60'

Responses

OK

Bodyapplication/json
metaobject(meta)required
meta.​versioninteger
Example: 1
meta.​nextstring
Example: "https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=10&timeout=60&ids=29%2C30"
meta.​exitstring
Example: "https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=0&timeout=60&ids=29%2C30"
meta.​topicstring
Example: "abc123"
meta.​resultSizeinteger
Example: 2
meta.​parametersobject(parameters)
resultsArray of objects(results)required
Array [
results[][].​idstring
Example: "29"
results[][].​callIdstring
Example: "J5WA4IAA@BXATD0S.glagqaseq108.DC2"
results[][].​costCenterstring
Example: "my billing code"
results[][].​dateReceivedstring
Example: "2023-08-03T12:09:43+0200"
results[][].​totalDurationinteger
Example: 82
results[][].​senderIsdnstring
Example: "00498912345678"
results[][].​senderFaxIdstring
Example: "Retarus/Doe"
results[][].​receiverIsdnstring
Example: "+4989262080440"
results[][].​receiverFaxIdstring
Example: "Retarus Faxolution"
results[][].​faxResolutionstring
Example: "HIGH"
results[][].​faxBaudRateinteger
Example: 33600
results[][].​faxPageCountinteger
Example: 1
results[][].​faxClassicStatusstring
Example: "OK"
results[][].​faxNumericStatusstring
Example: "2.0.0"
results[][].​archivingStatusstring
Example: "SUCCEEDED"
results[][].​archiveExpirystring
Example: "2023.08.10"
results[][].​documentsArray of objects(documents)
]
Response
application/json
{
  "meta": {
    "version": 1,
    "next": "https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=10&timeout=60&ids=29%2C30",
    "exit": "https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=0&timeout=60&ids=29%2C30",
    "topic": "abc123",
    "resultSize": 2,
    "parameters": { … }
  },
  "results": [
    { … },
    { … }
  ]
}

Download file by file name (Id.Extension)

Request

Download file by file name (Id.Extension)

Path
idstringrequired

File Id to be downloaded

extensionstringrequired

Extension of the file to be downloaded

curl -i -X GET \
  -u <username>:<password> \
  'https://developers.retarus.com/_mock/fax/fax2ws-pull-api/files/{id}.{extension}'

Responses

OK