# Faxolution for Applications status push notification API

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.


Version: v1

## Download OpenAPI description

[Faxolution for Applications status push notification API](https://developers.retarus.com/_bundle/fax/status-push-api.yaml)

## status push

Sends a status push message

### Send a status push message to the URL of your choice

 - [POST /your/desired/path](https://developers.retarus.com/fax/status-push-api/status-push/paths/~1your~1desired~1path/post.md): 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.