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.

Download OpenAPI description
fax4a-api.json
fax4a-api.yaml
Overview
URL

https://www.retarus.com/

Retarus

info@retarus.com

Terms of Service

Languages
Servers
Mock server

https://developers.retarus.com/_mock/fax/fax4a-api/

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/

Fax jobs

Send faxes

Operations

Fax reports

Operations

Fetch the status report for a single job

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.

Path
custNrstringrequired

Customer Number

jobIdstringrequired
curl -i -X GET \
  -u <username>:<password> \
  'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}'

Responses

Fax job status retrieved

Bodyapplication/json
jobIdstringrequired

The Job ID.

Example: "FJJ66GHGX105ZZBIELVCN1"
recipientStatusArray of objects(Fax Recipient With Status)required
Example: [{"number":"+49 89 1234567-8900","properties":null,"status":"OK","reason":"OK","sentTs":"2017-08-10T13:05:09Z","durationInSecs":19,"sentToNumber":"00498912345678900","remoteCsid":"+49/89/1234567-8900"}]
recipientStatus[].​numberstringrequired

The fax recipient's primary number (international format, e.g., +49891234678).

recipientStatus[].​propertiesArray of objects or null(Recipient Property)

Personalized data used for the cover page.

recipientStatus[].​statusstringrequired

Job status.

recipientStatus[].​reasonstringrequired

Explanation of the status.

recipientStatus[].​sentTsstring(date-time)

Timestamp which indicates when the fax was sent (in ISO 8601 format).

recipientStatus[].​durationInSecsintegerrequired

Duration of the fax transmission until received by the fax recipient.

recipientStatus[].​sentToNumberstring

Number to which the fax was sent.

recipientStatus[].​remoteCsidstring

Fax ID which identifies the fax recipient.

pagesintegerrequired

Number of pages in the fax.

Example: 1
referenceobject(Reference)
Response
application/json
{
  "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"
  }
}

Delete the status report for a single job

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.

Path
custNrstringrequired

Customer Number

jobIdstringrequired
curl -i -X DELETE \
  -u <username>:<password> \
  'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports/{jobId}'

Responses

Status report deleted

Bodyapplication/json
jobIdstring or nullrequired

The Job ID.

Example: "FJJ66GHGX105ZZBIELVCN1"
deletedbooleanrequired

Returns true if the job was successfully deleted, false otherwise. If absent in the response it means the job was successfully deleted.

Example: true
reasonstring

Missing if deletion was successful, otherwise one of the following reason messages is returned:

  • NOT_FOUND: No report exists for the given job id.
  • INTERNAL_ERROR: Unspecified server-side error.
Enum"NOT_FOUND""INTERNAL_ERROR"
Response
application/json
{
  "jobId": "FJJ66GHGX105ZZBIELVCN1",
  "deleted": true
}

Fetch available status reports for this account

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.

Path
custNrstringrequired

Customer Number

curl -i -X GET \
  -u <username>:<password> \
  'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports'

Responses

Status reports delivered

Bodyapplication/json
reportsArray of objects(Fax Report)required
Example: [{"jobId":"FJJ5Y09UM505ZZBIELCRYC","recipientStatus":[{"number":"+498912345678900","properties":null,"status":"OK","reason":"OK","sentTs":"2017-08-04T15:09:10Z","durationInSecs":19,"sentToNumber":"00498912345678900","remoteCsid":"+49/89/1234567-8900"}],"pages":1,"reference":{"customerDefinedId":"2017-08-04T15:09:10Z_customerDefinedId","billingCode":"2017-08-04T15:09:10Z_billingCode","billingInfo":"2017-08-04T15:09:10Z_billingInfo"}},{"jobId":"FJJ5WA23UO05ZZBIEL0JY5","recipientStatus":[{"number":"+498912345678901","properties":null,"status":"OK","reason":"OK","sentTs":"2017-08-03T10:07:31Z","durationInSecs":21,"sentToNumber":"00498912345678901","remoteCsid":"Retarus Faxolution"}],"pages":2,"reference":{"customerDefinedId":"2017-08-03T10:07:31Z_customerDefinedId","billingCode":"2017-08-03T10:07:31Z_billingCode","billingInfo":"2017-08-03T10:07:31Z_billingInfo"}}]
reports[].​jobIdstringrequired

The Job ID.

Example: "FJJ66GHGX105ZZBIELVCN1"
reports[].​recipientStatusArray of objects(Fax Recipient With Status)required
Example: [{"number":"+49 89 1234567-8900","properties":null,"status":"OK","reason":"OK","sentTs":"2017-08-10T13:05:09Z","durationInSecs":19,"sentToNumber":"00498912345678900","remoteCsid":"+49/89/1234567-8900"}]
reports[].​recipientStatus[].​numberstringrequired

The fax recipient's primary number (international format, e.g., +49891234678).

reports[].​recipientStatus[].​propertiesArray of objects or null(Recipient Property)

Personalized data used for the cover page.

reports[].​recipientStatus[].​statusstringrequired

Job status.

reports[].​recipientStatus[].​reasonstringrequired

Explanation of the status.

reports[].​recipientStatus[].​sentTsstring(date-time)

Timestamp which indicates when the fax was sent (in ISO 8601 format).

reports[].​recipientStatus[].​durationInSecsintegerrequired

Duration of the fax transmission until received by the fax recipient.

reports[].​recipientStatus[].​sentToNumberstring

Number to which the fax was sent.

reports[].​recipientStatus[].​remoteCsidstring

Fax ID which identifies the fax recipient.

reports[].​pagesintegerrequired

Number of pages in the fax.

Example: 1
reports[].​referenceobject(Reference)
Response
application/json
{
  "reports": [
    { … },
    { … }
  ]
}

Perform bulk operations on the status 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.

Path
custNrstringrequired

Customer Number

Bodyapplication/jsonrequired

Array of jobIds to delete from the API.

actionstringrequired

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.

jobIdsArray of stringsrequired

List of Job IDs to be processed in bulk

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"
    ]
  }'

Responses

Depending on the request type, this returns a reports item containing either:

  • an array of Fax Report items for the bulk GET (same as getAllStatusReports).
  • an array of Job Delete Report items for the bulk DELETE.
Bodyapplication/json
reportsArray of objects(Bulk Job Reports Response)
Response
application/json
{
  "value": {
    "reports": [ … ]
  }
}

Delete the oldest status reports for this account

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.

Path
custNrstringrequired

Customer Number

curl -i -X DELETE \
  -u <username>:<password> \
  'https://developers.retarus.com/_mock/fax/fax4a-api/{custNr}/fax/reports'

Responses

Status reports deleted

Bodyapplication/json
reportsArray of objects(Job Delete Report)
Example: [{"jobId":"FJJ5Y09UM505ZZBIELCRYC","deleted":true},{"jobId":"FJJ5WA23UO05ZZBIEL0JY5","deleted":true},{"jobId":"FJJ5WA0FWM05ZZBIELZPE4","deleted":false,"reason":"NOT_FOUND"},{"jobId":"FJJ5Y07H3805ZZBIELBAPL","deleted":true},{"jobId":"FJJ5WA25VB0BRN8TPSGGVY","deleted":false,"reason":"INTERNAL_ERROR"},{"jobId":"FJJ5WA253505ZZBIELEKRC","deleted":true},{"jobId":"FJJ5WA24GI0BRN8TPSWAVM","deleted":true}]
Response
application/json
{
  "reports": [
    { … },
    { … },
    { … },
    { … },
    { … },
    { … },
    { … }
  ]
}