Faxolution for Applications (Fax4A) REST API (v1)
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: DC in Frankfurt
- DE2: DC in Munich
United States
HA region US, including these data centers:
- US1: DC Ashburn
- US2: DC Secaucus
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.
https://developers.retarus.com/_mock/fax/fax4a-api/
https://faxws.de1.retarus.com/rest/v1/
https://faxws.de2.retarus.com/rest/v1/
https://faxws-ha.de.retarus.com/rest/v1/
https://faxws.us1.retarus.com/rest/v1/
https://faxws.us2.retarus.com/rest/v1/
https://faxws-ha.us.retarus.com/rest/v1/
https://faxws.ch1.retarus.com/rest/v1/
https://faxws.sg1.retarus.com/rest/v1/
Request
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).
Please note: If you sent the fax job requests via a high availability URL, you have to poll the status from both included data centers. E.g., US1 and US2 in case of the US high availability URL. Please do not poll statuses directly from an HA URL but use the specific ones for the data centers.
- Mock server
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}
- Retarus data center in Germany
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in Germany
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- High availability URL for German data centers
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in USA
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in USA
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- High availability URL for US data centers
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in Switzerland
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in Singapore
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}'
Fax job status retrieved
The fax recipient's primary number (international format, e.g., +49891234678).
Personalized data used for the cover page.
Timestamp which indicates when the fax was sent (in ISO 8601 format).
Duration of the fax transmission until received by the fax recipient.
{ "jobId": "FJJ66GHGX105ZZBIELVCN1", "recipientStatus": [ { … } ], "pages": 1, "reference": { "customerDefinedId": "2017-08-10T13:05:09Z_customerDefinedId", "billingCode": "2017-08-10T13:05:09Z_billingCode", "billingInfo": "2017-08-10T13:05:09Z_billingInfo" } }
Request
Deletes the status report for a single job. Returns the Job ID."
Please note: If you sent the fax job requests via a high availability URL, you have to send a delete request to both included data centers. Else, it will be likely that the job was not processed in the data center you referenced and hence cannot be deleted there. Please do not send a delete request directly to an HA URL but use the specific ones for the data centers.
- Mock server
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}
- Retarus data center in Germany
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in Germany
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- High availability URL for German data centers
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in USA
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in USA
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- High availability URL for US data centers
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in Switzerland
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- Retarus data center in Singapore
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}'
{ "jobId": "FJJ66GHGX105ZZBIELVCN1", "deleted": true }
Request
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: If you sent the fax job requests via a high availability URL, you have to poll the status from both included data centers. E.g., US1 and US2 in case of the US high availability URL. Please do not poll statuses directly from an HA URL but use the specific ones for the data centers.
- Mock server
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports
- Retarus data center in Germany
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Germany
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports
- High availability URL for German data centers
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in USA
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in USA
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports
- High availability URL for US data centers
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Switzerland
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Singapore
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports'
Status reports delivered
The fax recipient's primary number (international format, e.g., +49891234678).
Personalized data used for the cover page.
Timestamp which indicates when the fax was sent (in ISO 8601 format).
Duration of the fax transmission until received by the fax recipient.
{ "reports": [ { … }, { … } ] }
Request
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: If you sent the fax job requests via a high availability URL, you have to send a delete request or a status poll request to both included data centers. Else, it will be likely that the job was not processed in the data center you referenced and hence cannot be deleted or no status is available there. Please do not send a request directly to an HA URL but use the specific ones for the data centers.
Array of jobIds to delete from the API.
Defines the action to be performed on all jobs whose Job ID is provided in the jobIds
list
Possible options are:
- DELETE: Bulk delete the requested jobs
- GET: Bulk get the requested jobs
Both options are case insensitive.
- Mock server
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports
- Retarus data center in Germany
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Germany
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports
- High availability URL for German data centers
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in USA
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in USA
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports
- High availability URL for US data centers
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Switzerland
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Singapore
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
-u <username>:<password> \
'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports' \
-H 'Content-Type: application/json' \
-d '{
"action": "GET",
"jobIds": [
"FJJ5Y09UM505ZZBIELCRYC",
"FJJ5WA23UO05ZZBIEL0JY5",
"FJJ5WA0FWM05ZZBIELZPE4",
"FJJ5Y07H3805ZZBIELBAPL",
"FJJ5WA25VB0BRN8TPSGGVY",
"FJJ5WA253505ZZBIELEKRC",
"FJJ5WA24GI0BRN8TPSWAVM"
]
}'
{ "value": { "reports": [ … ] } }
Request
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: If you sent the fax job requests via a high availability URL, you have to send a delete request to both included data centers. Else, it will be likely that the job was not processed in the data center you referenced and hence cannot be deleted there. Please do not send a delete request directly to an HA URL but use the specific ones for the data centers.
- Mock server
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports
- Retarus data center in Germany
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Germany
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports
- High availability URL for German data centers
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in USA
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in USA
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports
- High availability URL for US data centers
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Switzerland
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports
- Retarus data center in Singapore
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports'
Status reports deleted
{ "reports": [ { … }, { … }, { … }, { … }, { … }, { … }, { … } ] }