Faxolution for Applications status push notification API (v1)

This document describes usage and possible content of the status push API. You can use it to be proactively informed about the outcome of the fax messages you sent with Faxolution for Applications. Both XML and JSON are available as file type. We recommend to use this option rather than polling the status via the Faxolution for Applications API or getting a notification via email.

Please note: The following schema description as well as the examples refer to the default layout of the push message for XML and JSON. You can request an individual status push template from our implementation team. Also, some elements only show up in the push message, if they were referenced in the fax request. This is reflected in the examples.

Download OpenAPI description
status-push-api.json
status-push-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/status-push-api/

status push

Sends a status push message

Operations

Send a status push message to the URL of your choice

Request

Notification via HTTP implies the customer is operating an HTTP server that accepts the specified URL HTTP POST requests from Retarus' infrastructure. The customer should provide and configure:

  • A target web service accepting HTTP POST requests
  • An authentication method. The following are supported at the moment:
    • HTTP_BASIC
    • HTTP_DIGEST
    • OAUTH2
    • NONE

The parameters should be provided in each HTTP request made in Faxolution for Applications. By default, the format of the status push is the same as the response to a getFaxReports in the Faxolution for Applications SOAP API. If you prefer to use a custom format, please contact Retarus.

In the corresponding HTTP response from the customer’s server, a status code in the 200-299 range is expected if the HTTP request was successfully received. If there are errors, a status code in the 400-499 range (in cases of erroneous requests) or the 500-599 range (in cases of HTTP server errors) should be provided.

Body
required

Fax status push message as a ReportResponse object

jobIdstring

The Job ID. Summarizes all faxes of a send request, if there is more than one.

reportMailobject(reportMail)
httpStatusPushobject(httpStatusPush)
faxRecipientsArray of objects(faxRecipients)
documentsArray of objects(documents)
optionsobject(options)
pagesinteger(pages)

Number of pages in the fax document, as long as it was successfully delivered.

curl -i -X POST \
  https://developers.retarus.com/_mock/fax/status-push-api/your/desired/path \
  -H 'Content-Type: text/xml' \
  -d '[object Object]'

Responses

OK: The job was processed properly on your side (example)