# 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: v1

## Servers

Retarus data center DE1 in Germany
```
https://api.de1.retarus.com/faxin/rest/v1
```

Retarus data center DE2 in Germany
```
https://api.de2.retarus.com/faxin/rest/v1
```

Retarus data center US1 in United States
```
https://api.us1.retarus.com/faxin/rest/v1
```

Retarus data center US2 in United States
```
https://api.us2.retarus.com/faxin/rest/v1
```

Retarus data center CH1 in Switzerland
```
https://api.ch1.retarus.com/faxin/rest/v1
```

Retarus data center SG1 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

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