# Fax2WSPull

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.


Version: v0

## Servers

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
```

## Security

### httpBasicAuth

The format is `<Retarus Customer Number>:<Password>`, encoded via Base 64.
The passwords are provided by Retarus and they can be associated to one or more incoming telephone numbers.
As for example:
```
Authorization: Basic OTk5OTk6S0tkUVNHSU1XME1mOTdiVA==
```
Multiple processes can be operated concurrently by the Webservice using the same 
password or multiple passwords.


Type: http
Scheme: basic

## Download OpenAPI description

[Fax2WSPull](https://developers.retarus.com/_bundle/fax/fax2ws-pull-api.yaml)

## Fax2WSPull Client

### Retrieve fax jobs from a topic and confirm the receipt.

 - [POST /topics/{topic}](https://developers.retarus.com/fax/fax2ws-pull-api/fax2wspull-client/pollfaxinformation.md): 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.

### Download file by  file name (Id.Extension)

 - [GET /files/{id}.{extension}](https://developers.retarus.com/fax/fax2ws-pull-api/fax2wspull-client/pollfaxdocuments.md): Download file by  file name (Id.Extension)