# Faxolution for Applications (Fax4A) REST API

Retarus' Faxolution for Applications webservice facilitates automation of
the fax transmission process. In addition, it also allows you to monitor
the status of a sent fax and delete archived reports. The Webservice
communicates via RESTful API using JSON. The programming language with which the
Webservice client is implemented is not restricted by the Webservice itself.
Fax transmission is generally divided into the following steps:
* Create a fax job and send it to the webservice

then either
* Retrieve completed fax jobs
GET /{custNr}/fax/reports
* Retrieve the status details for the completed jobs individually or in bulk
GET /{custNr}/fax/reports/{jobId} or POST /{custNr}/fax/reports
* Delete the retrieved jobs individually or in bulk
DELETE /{custNr}/fax/reports/{jobId} or POST /{custNr}/fax/reports

or
* Receive the fax job status per HTTP push and/or email status report

Fax job data will be automatically deleted after the configured retention time.
For highest process safety standards, we operate two high availability (HA) regions, where data centers are clustered. This is how the HA regions are composed:
**Germany**
HA region DE, including these data centers:
* DE1
* DE2

**United States**
HA region US, including these data centers:
* US1
* US2

Please see the individual operations for details on how to work with HA settings.
To obtain a test account for this service or any of our other fax services, please contact Retarus.

Version: v1

## Servers

Retarus data center in Germany
```
https://faxws.de1.retarus.com/rest/v1
```

Retarus data center in Germany
```
https://faxws.de2.retarus.com/rest/v1
```

High availability URL for German data centers
```
https://faxws-ha.de.retarus.com/rest/v1
```

Retarus data center in USA
```
https://faxws.us1.retarus.com/rest/v1
```

Retarus data center in USA
```
https://faxws.us2.retarus.com/rest/v1
```

High availability URL for US data centers
```
https://faxws-ha.us.retarus.com/rest/v1
```

Retarus data center in Switzerland
```
https://faxws.ch1.retarus.com/rest/v1
```

Retarus data center in Singapore
```
https://faxws.sg1.retarus.com/rest/v1
```

## Security

### httpBasicAuth

Each HTTP Request must be authenticated by Basic Authorization.

```
Authorization: Basic Base64Encoded(username:password)
```
Where `Base64Encoded(username:password)` is an actual Base64 encoded string of the `username:password`.
*Example*:
username: John
password: secret
Base64-encoding of `John:secret` is `Sm9objpzZWNyZXQ=`.

```
…
Authorization: Basic Sm9objpzZWNyZXQ=
…
```
Retarus can configure multiple forms of access (Login IDs) for the Webservice that can be managed via the Retarus
EAS Portal. Multiple processes can be operated concurrently by the Webservice using multiple Login IDs, making
it possible to have a configuration saved for each process.
The job and report data for one Login ID are not viewable or available in the other access options, which means
that a fax job’s status report can only be requested or deleted under the Login ID used to create it.
As an additional layer of security it is possible to restrict access for each Login ID to a pre-defined
list of IP addresses and/or subnets (IP address whitelisting).
If an account is so configured, all requests coming from IP addresses which are not on the list will be rejected.
The configuration of IP address whitelisting is performed in the EAS portal.

Type: http
Scheme: basic

## Download OpenAPI description

 - [Faxolution for Applications (Fax4A) REST API](https://developers.retarus.com/_bundle/fax/fax4a-api.yaml)

## Fax jobs

 - [POST /{custNr}/fax](https://developers.retarus.com/fax/fax4a-api/fax-jobs/sendjobrequest.md): This method is used to prepare fax jobs to be transferred for processing. If a valid FaxJobRequest has been received by the Webservice, the Webservice sends a Job ID back that must be specified by the
## Fax reports

 - [GET /{custNr}/fax/reports/{jobId}](https://developers.retarus.com/fax/fax4a-api/fax-reports/getstatusreport.md): With the assistance of this URL resource, a status report for a fax job can be requested by jobId. A job's status can be queried until its report data is deleted. You can initiate deletion of the data
 - [DELETE /{custNr}/fax/reports/{jobId}](https://developers.retarus.com/fax/fax4a-api/fax-reports/deletestatusreport.md): Deletes the status report for a single job. Returns the Job ID.
 - [GET /{custNr}/fax/reports](https://developers.retarus.com/fax/fax4a-api/fax-reports/getallstatusreports.md): This URL returns a list of available status reports for completed fax jobs for the current account. Status reports are available for up to 30 days or until deleted. IMPORTANT: The results are limited
 - [POST /{custNr}/fax/reports](https://developers.retarus.com/fax/fax4a-api/fax-reports/bulkstatusreports.md): It is possible to perform bulk operations on the status reports through a POST on the `/{custNr}/fax/reports` endpoint. The required parameters are: * the type of action to be performed * A list of Jo
 - [DELETE /{custNr}/fax/reports](https://developers.retarus.com/fax/fax4a-api/fax-reports/deleteoldeststatusreports.md): Deletes up to 1000 status reports for completed fax jobs for the current account, starting from the oldest ones. It returns the jobIds of deleted job reports. IMPORTANT: In case there are more than 10