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:
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
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:
United States
HA region US, including these data centers:
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/
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.
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
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" } }
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.
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports/{jobId}
curl -i -X DELETE \
-u <username>:<password> \
'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}'
{ "jobId": "FJJ66GHGX105ZZBIELVCN1", "deleted": true }
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.
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports
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": [ { … }, { … } ] }
It is possible to perform bulk operations on the status reports through a POST on the /{custNr}/fax/reports
endpoint. The required parameters are:
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:
Both options are case insensitive.
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports
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": [ … ] } }
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.
https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports
https://faxws.de1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.de2.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws-ha.de.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.us1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.us2.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws-ha.us.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.ch1.retarus.com/rest/v1/{custNr}/fax/reports
https://faxws.sg1.retarus.com/rest/v1/{custNr}/fax/reports
curl -i -X DELETE \
-u <username>:<password> \
'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports'
Status reports deleted
{ "reports": [ { … }, { … }, { … }, { … }, { … }, { … }, { … } ] }