# 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 REST 1.0 (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 Send faxes ### Send a fax - [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 client when querying the job status. ## Fax reports Retrieve the fax status reports ### Fetch the status report for a single job - [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 by calling deleteStatusReport, and in any case the data will be automatically be deleted upon the expiration of the configurable time frame (by default 30 days). ### Delete the status report for a single job - [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. ### Fetch available status reports for this account - [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 to the oldest 1000 entries. It is recommended to delete the status reports after fetching them in order to retrieve the following ones. Please note: This endpoint should only be used with a datza center specifc URL. This endpoint would return "inconsistent" results depending on the data center the request is processed by. ### Perform bulk operations on the status reports - [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 Job IDs on which the operation should be performed Status reports are available for up to 30 days or until deleted. The maximum number of jobs per POST request is set to 1000. Please note: This edpoint should only be used with a datza center specifc URL. This endpoint could return an error about unknown job IDs depending on the data center the request is processed by. ### Delete the oldest status reports for this account - [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 1000 completed job reports, multiple calls of this method might be needed to delete them all. Please note: This edpoint should only be used with a datza center specifc URL. This endpoint could return an error about unknown job IDs depending on the data center the request is processed by.