Fax-for-Applications API - Reworked

Retarus Fax-for-Applications automates the fax transmission process. It also allows you to monitor fax status and delete archived reports. The service uses a REST 1.0 (JSON) interface. You can implement the Fax-for-Applications client in any programming language.

Fax transmission generally follows these steps:

1. Create and send a fax job to Fax-for-Applications.

2. Retrieve the job status via polling or via a push service (HTTP or mail).

3. Delete fax reports when no longer needed.

Version & media

Authentication

The API uses HTTP Basic Authentication for all requests. Each request must include:

Authorization: Basic Base64Encoded(username:password)

Example

• Username: John

• Password: secret

• Base64-encoding of John:secret is Sm9objpzZWNyZXQ=

• Header: Authorization: Basic Sm9objpzZWNyZXQ=

Login ID is managed via the Retarus EAS Portal. Jobs created under one Login ID are isolated and cannot be accessed using another.

As an additional layer of protection, you can configure IP allowlisting per Login ID to restrict access to specific IP addresses or subnets.

📌 Note

For more information about authorization, refer to the API Center.

Service endpoints

The Fax-for-Applications service is available via highly available (HA) endpoints or specific data center URLs:

For additional connection options, contact Retarus Support.

Key concepts

Status report & job data retention

• Status reports: Available for retrieval for up to 30 days or until manually deleted.

• Job data: Automatically deleted after the configured retention period.

High availability (HA) handling

If you submit fax jobs via a HA URL:

• Always query or delete reports through the data center URLs (e.g., US1 and US2 for USA jobs).

• Never send status queries or delete requests to an HA URL.

• Always check both data centers since processing might not have completed across both.

Job validity periods

• By default, jobs become valid immediately upon creation and expire one month later.

• You can specify custom validity periods using ISO 8601 format:

  • Timestamps for specific points in time (example: "2023-12-31T23:59:59Z")

  • Duration strings for time periods (example: "P30D" for 30 days)

• Jobs automatically expire once the specified end time is reached or when the duration period elapses.

Job deletion rules

• Deletion operations can handle up to 1000 jobs per request.

• If more jobs are available, multiple requests are needed.

Limitations & constraints

Document constraints

Status report limitations

• Status reports are limited to the oldest 1000 entries per request.

• To retrieve more reports, you must delete processed reports first.

• Reports are stored for up to 30 days by default.

Main operations

The following operations are available.

📌 Customer number

In all API endpoints, {custNr} refers to your Retarus customer number (e.g., 999901). This is a unique identifier for your account and must be included in all API requests.

📌 Note
For full operation details, parameters, and request/response examples, see the API Center documentation.

Data structure overview

Fax jobs and their related operations use structured JSON data. Below is an overview of the key components and supporting objects used throughout the API.

Main data models

Supporting data structures

Error response structure

All error responses follow a standard format containing a code and message:

{
  "code": 400,
  "message": "Validation of job request failed: 'No number available for rcpt
              FNLAJR3BK80D8LLWADCPYL'"
}

Authentication failures are responded to with:

{
  "code": 401,
  "message": "Authentication failed"
}

📌 Note
Schema field details and example payloads are available in the API Center documentation. Field visibility may depend on the request type (e.g., GET vs DELETE).

Pagination of status reports

To work with more than 1000 status reports:

1. Retrieve the first batch of up to 1000 reports using GET /{custNr}/fax/reports.

2. Process the retrieved reports.

3. Delete the reports you've processed using DELETE /{custNr}/fax/reports.

4. Repeat the process to get the next batch of reports.

There is no explicit pagination parameter - you must delete processed reports to access the next set.

Troubleshooting