openapi: 3.0.3
info:
  title: Faxolution for Applications status push notification API
  version: v1
  description: >
    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.
  contact:
    name: Retarus
    url: https://www.retarus.com/
    email: info@retarus.com
  termsOfService: https://www.retarus.com/us/legal-disclaimer/
tags:
  - name: status push
    description: Sends a status push message
paths:
  /your/desired/path:
    post:
      tags:
        - status push
      summary: Send a status push message to the URL of your choice
      description: >
        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.
      requestBody:
        description: Fax status push message as a ReportResponse object
        required: true
        content:
          text/xml:
            schema:
              $ref: '#/components/schemas/ReportResponse'
            examples:
              sendStatusPushSmall:
                $ref: '#/components/examples/sendStatusPushSmall'
              sendStatusPushLarge:
                $ref: '#/components/examples/sendStatusPushLarge'
          application/json:
            schema:
              $ref: '#/components/schemas/ReportResponse'
            examples:
              sendStatusPushSmall:
                $ref: '#/components/examples/sendStatusPushSmall'
              sendStatusPushLarge:
                $ref: '#/components/examples/sendStatusPushLarge'
      responses:
        '200':
          description: 'OK: The job was processed properly on your side (example)'
        '400':
          description: 'BAD_REQUEST: Client side error (example)'
        '500':
          description: 'SERVER_ERROR: Server side error (example)'
components:
  schemas:
    ReportResponse:
      type: object
      description: The root element of the fax job report
      properties:
        jobId:
          type: string
          description: >-
            The Job ID. Summarizes all faxes of a send request, if there is more
            than one.
        reportMail:
          $ref: '#/components/schemas/reportMail'
        httpStatusPush:
          $ref: '#/components/schemas/httpStatusPush'
        faxRecipients:
          $ref: '#/components/schemas/faxRecipients'
        documents:
          $ref: '#/components/schemas/documents'
        options:
          $ref: '#/components/schemas/options'
        pages:
          $ref: '#/components/schemas/pages'
    reportMail:
      type: object
      properties:
        successAddress:
          type: string
          description: >
            Email address, to which delivery confirmations notifications should
            be sent.


            `Example:` "john.doe@retarus.com"
        failureAddress:
          type: string
          description: >
            Email address, to which a notification should be sent when errors
            occur.


            `Example:` "jane.doe@retarus.com"
    httpStatusPush:
      type: object
      properties:
        url:
          type: string
          description: |
            URL where the status is pushed to.

            `Example:` "http://retarus.com/testpath/test-target"
        principal:
          type: string
          description: >-
            The user name to authenticate with the status push endpoint, if
            required. When using OAUTH2 this is the client id to obtain access
            tokens.
        credentials:
          type: string
          description: >-
            The password to authenticate with the status push endpoint, if
            required. When using OAUTH2 this is the client secret to obtain
            access tokens.
        authMethod:
          type: string
          description: |
            Authentication method. Possible values are:
            * HTTP_BASIC
            * HTTP_DIGEST
            * OAUTH2
            * NONE

            `Default:` "NONE"
    faxRecipients:
      type: array
      items:
        $ref: '#/components/schemas/faxRecipient'
      xml:
        wrapped: true
    faxRecipient:
      type: object
      properties:
        number:
          type: string
          description: |
            Dialed number (international format, e.g., +4989123456789).

            `Example:` "+4989123456789"
        faxID:
          type: string
          description: >
            The ID of an individual fax transmission, set by Faxolution for
            Applications


            `Example:` FNIJPNJYNA06EDIJNFUO1Q
        properties:
          type: array
          nullable: true
          description: Personalized data used for the cover page.
          items:
            $ref: '#/components/schemas/property'
          xml:
            wrapped: true
        status:
          type: string
          description: >
            Job status. Possible values:

            * OK: All pages were successfully delivered.

            * BUSY: Destination number busy, e.g. recipient fax machine
            receiving long fax or high fax volume. 

            `Sender action:` Retry, contact recipient if necessary.

            * NOFAX: Call not received by fax device – call answered by a
            person, answering machine or modem. Could also indicate Carrier
            interconnect issue.

            `Sender action:` Retry, contact recipient if necessary. Open Retarus
            support ticket if issue persists.

            * NOFAX_DIS: Call not received by fax device (disconnect) –
            recipient ended the communication, call answered by a person who
            hung up. Could also indicate Carrier interconnect issue.

            `Sender action:` Retry, contact recipient if necessary. Open Retarus
            support ticket if issue persists.

            * NOFAX_TO: Call was accepted but no fax protocol signal was
            provided (timeout). Timeout occurred while waiting for recipient to
            be identified as a fax device. Could also indicate Carrier
            interconnect issue.

            `Sender action:` Retry, contact recipient if necessary. Open Retarus
            support ticket if issue persists.

            * RING_TO: Timeout occurred while waiting for response – fax device
            not answering, e.g. fax device powered off, call automatically
            transferred to a telephone, fax device out of paper.

            `Sender action:` Retry, contact recipient if necessary. Open Retarus
            support ticket if issue persists.

            * CHANGED_NO: Changed Number, received recorded message that dialed
            number has changed.

            `Sender action:` Contact recipient.

            * DIAL_NC: No Connection, call setup failed at Carrier level, e.g.
            telephone company rejected dialed number as incomplete, invalid or
            temporarily disconnected.

            `Sender action:` Verify number. Retry. Open Retarus support ticket
            if issue persists.

            * DIAL_TO: Timeout occurred at Carrier level during call setup.

            `Sender action:` Verify number. Retry. Contact recipient. Open
            Retarus support ticket if issue persists.

            * WRONG_NO: Wrong, invalid, or unassigned number.

            `Sender action:` Verify number. Retry.

            * INVALID_NO: Invalid number structure

            `Sender action:` Verify number. Retry.

            * WOUT_TO: Output Window Timeout, call setup timeout before there is
            a ring tone (this is normally a carrier problem).

            `Sender action:` Verify number. Contact recipient. Open Retarus
            support ticket if issue persists.

            * CANCELLED: The fax job was manually cancelled by the sender. 

            `Sender action:` Resend, if applicable.

            * EXP_CANC: Expiry Cancellation, the fax job was not completed and
            was automatically cancelled at the expiry timestamp. 

            `Sender action:` Contact Administrator regarding expiry timestamp
            setting or root causes.

            * RENDERING_ERROR: Unable to convert attachment(s) and / or
            coversheet into a fax document, e.g., a password protected PDF
            document.

            `Sender action:` Verify document is in a supported file format and
            not password protected or encrypted, then retry. Contact
            Administrator regarding list configuration in the EAS* portal.

            * UNKNOWN_FAX_FILE: At least one of the files to be sent is missing
            or the file name is missing. Faxolution for Applications only:

            `Sender action:` Resend with file name(s).

            * UNSUPPORTED_FILETYPE: Unable to convert document into a fax
            because the document has an attachment which lacks a supported
            filename extension.

            `Sender action:` Verify if the document is in a supported file
            format and has a valid file name extension, then retry.

            * BAD_LINES: Fax might be illegible due to degraded transmission or
            line errors and / or the remote station does not support error
            correction.

            `Sender action:` Retry. Contact recipient. Open Retarus support
            ticket if issue persists.

            * DIAL_GF: Dial General Failure, call setup failure at the carrier
            level.

            `Sender action:` Retry. Contact recipient. Open Retarus support
            ticket if issue persists.

            * EOD_FAILED: The fax is confirmed as not received, although in
            practice it often still successfully reaches the recipient. For
            example, the reverse channel is suddenly broken in one direction
            because the party is not protocol-compliant or there is a
            communication problem. 

            May be due to line quality (noise). Appears at a later stage in
            transmission than the PAGE_SEND_ERR code.

            `Sender action:` Retry. Open Retarus support ticket if issue
            persists.

            * FANS_GF: Fax General Failure, connection was interrupted due to
            protocol errors in counterpart station during protocol interchange. 

            `Sender action:` Retry. Contact recipient. Open Retarus support
            ticket if issue persists.

            * NO_REMOTEINFO: Remote station hung up before it transmitted its
            identity name or before it was able to configure arrange a different
            transmission mode. 

            `Sender action:` Retry. Contact recipient. Open Retarus support
            ticket if issue persists.

            * NO_TRAIN/ NO_TRAINING: No Successful Training Possible Remote
            disconnect during negotiation of fax speed and features before the
            final page is delivered. May also map to the NOFAX_DIS status code.

            `Sender action:` Retry. Open Retarus support ticket if issue
            persists.

            * PAGE_SEND_ERR: Fax job could not be sent, e.g. fax device out of
            paper, connection was interrupted, or protocol error terminated
            transmission prior to final page Appears at earlier stage in
            transmission than EOD_FAILED status code: 

            `Sender action:` Retry. Open Retarus support ticket if issue
            persists.

            * REM_DIS . Remote disconnect after detection of fax tones.
            Recipient hung up. 

            `Sender action:` Retry, contact recipient if necessary. Open Retarus
            support ticket if issue persists.

            * BLACKLIST: Public Blacklist, number may be registered with, e.g.,
            BITKOM Robinson List (Germany- based numbers) or ECOFAX
            (France-based numbers) and cannot be contacted because the
            applicable list has been activated by regulatory authorities.

            `Sender action:` Contact recipient.  

            * BAD_FILE: An internal error occurred during processing prior to
            establishing a fax transmission. 

            `Sender action:` Retry. Open Retarus support ticket if issue
            persists.

            * EXPIRED: An internal error occurred during processing prior to
            establishing a fax transmission. 

            `Sender action:` Retry. Open Retarus support ticket if issue
            persists.

            * FAXUNIT_NA: An internal error occurred during processing prior to
            establishing a fax transmission. 

            `Sender action:` Retry. Open Retarus support ticket if issue
            persists.

            * MISSING_FAX_FILE: An internal error occurred during processing
            prior to establishing a fax transmission.
             `Sender action:` Retry. Open Retarus support ticket if issue persists.
            * NOFILE: An internal error occurred during processing prior to
            establishing a fax transmission. 
             `Sender action:` Retry. Open Retarus support ticket if issue persists.
            * COMERROR: An unknown error has occurred during transmission. An
            internal error occurred during processing prior to establishing a
            fax transmission. 
             `Sender action:` Retry. Open Retarus support ticket if issue persists.
            * FAILURE: An unknown error has occurred when preparing the job for
            transmission. An internal error occurred during processing prior to
            establishing a fax transmission.
             `Sender action:` Retry. Check the provided reason for hints. Open Retarus support ticket if issue persists.
        reason:
          type: string
          description: Explanation of the status.
        sentTs:
          type: string
          description: >-
            Timestamp which indicates when the fax was sent (in ISO 8601
            format).
        durationInSecs:
          type: integer
          description: >-
            Duration of the fax transmission until received by the fax
            recipient.
        sentToNumber:
          type: string
          description: Number to which the fax was sent.
        remoteCsid:
          type: string
          description: Fax ID which identifies the fax recipient.
      xml:
        name: faxRecipient
    property:
      type: object
      description: >
        A cover page can be personalized for each individual recipient and then
        attached to the front of each fax document.


        This object allows specifying a value for each of the keys in the
        template.


        See \<\<common-fax4ba-cover-page-personalization\>\> for additional
        information.
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: >
            The key in a key / value pair used to fill the variables of a cover
            page in the fax send request.   
          example: key123
        value:
          type: string
          description: >
            The value in a key / value pair used to fill the variables of a
            cover page in the fax send request.
          example: value123
      xml:
        name: property
    documents:
      type: array
      items:
        $ref: '#/components/schemas/document'
      xml:
        wrapped: true
    document:
      type: object
      properties:
        name:
          type: string
          description: >
            Document file name; the file extension is important for determining
            the file type, e.g., `Invoice-2023-01.pdf`. Please note: The maximum
            possible length of a file name is 32 characters. 

            Allowed characters are: `a-zA-Z0-9-_.`, and no whitespaces, slashes,
            or other special characters are permitted.


            `Example:` "test-document-inline-byte-array.txt"
        isText:
          type: boolean
          description: Currently is not enabled in this version
        charset:
          type: string
          description: |
            Character encoding of plain text documents (*.txt). Possible values:

            * US-ASCII
            * UTF-8
            * UTF-16
            * UTF-16BE
            * UTF-16LE
            * ISO-8859-1
            * Windows-1252
      xml:
        name: document
    options:
      type: object
      properties:
        resolution:
          type: string
          description: |
            The fax’s resolution. Possible values are:
            * LOW
            * HIGH
        tsid:
          type: string
          description: Fax ID which identifies the fax sender.
        header:
          type: string
          description: >
            The content of the header, including control characters. 


            `Example:` "%tz=CEST Testfax: CSID: %C Recipient number: %# Date:
            %d.%m.%Y %H:%M %z"
        isBlacklistEnabled:
          type: boolean
          description: >-
            Flag for the use of the Robinson List (only for numbers in Germany),
            ECOFAX (for numbers in France), or Retarus' own deny list.
        isExpress:
          type: boolean
          description: Flag for transmissions sent as express.
        overlay:
          $ref: '#/components/schemas/overlay'
        coverpageTemplateName:
          type: string
          description: Name of the cover page’s template
        scheduleTS:
          type: string
          description: >-
            scheduled transmission start in the future, if not being sent
            immediately
        jobExpiryMinutes:
          type: integer
          description: Termination time for attempts to send a fax job
        billingCode:
          type: string
          description: >-
            Information on the cost center; format is arbitrary (max. 80
            characters)
        billingInfo:
          type: string
          description: >-
            Additional data for internal customer accounting (max. 80
            characters)
        jobReference:
          type: string
          description: >
            reference information on the fax job; format is arbitrary, e.g., for
            a customer-defined equivalent to the Job ID (this would be
            concurrently managed along with the actual Job ID, but will not
            overwrite it; max. 256 characters)
    overlay:
      type: object
      properties:
        name:
          type: string
          description: |
            the template name, without the path information and file extension.
          example: overlay_template1
        mode:
          type: string
          description: >
            specifies the page in the document where the template (overlay) will
            be applied. Possible values:

              * ALL_PAGES: the overlay is applied to all pages
              * NO_OVERLAY: no overlay is used (returns the same result as if "no overlay" had been specified in the options)
              * FIRST_PAGE: the overlay is applied only to the first page (if you are using a cover  page, it is considered the first page)
              * LAST_PAGE: the overlay is applied only to the last page
              * ALL_BUT_FIRST_PAGE: the overlay is applied to all pages except for the first (if you are using a cover page, the overlay will be applied to all other pages because the cover page is considered the first page)
              * ALL_BUT_LAST_PAGE: the overlay is applied to all pages except the last one
              * ALL_BUT_FIRST_AND_LAST_PAGE: the overlay is applied to all pages except for the first and the last (the cover page is considered the first page if this mode is used)
              * FIRST_FILE: if the faxed document consists of multiple files, the overlay will only be used on the first file's pages (the cover page is considered not to belong to any file and does not an overlay in this mode)        
    pages:
      type: integer
      description: >-
        Number of pages in the fax document, as long as it was successfully
        delivered.
  examples:
    sendStatusPushSmall:
      summary: Example for a lean message
      value:
        jobId: FJIJPNJYN906EDIJNFGI5S
        faxRecipients:
          - number: '+4989123456789'
            status: OK
            sentTs: '2023-01-03T15:38:08Z'
            sentToNumber: '004989123456789'
            remoteCsid: +49/89/1234567-89
        documents:
          - name: document.pdf
        options:
          billingCode: My BC 123
          billingInfo: Default billing code
          jobReference: My Reference ID
        pages: 2
    sendStatusPushLarge:
      summary: Example for a full-scale message
      value:
        jobId: FJIJPNJYN906EDIJNFGI5T
        reportMail:
          successAddress: john.doe@retarus.com
          failureAddress: jane.doe@retarus.com
        httpStatusPush:
          url: https://statuslistener.example.com:9564/Faxolution- v3.0
        faxRecipients:
          - number: '+4989123456789'
            faxID: FNIJPNJYNA06EDIJNFUO1Q
            properties:
              - key: FromName
                value: Jane Doe
              - key: ToName
                value: Jill Doe
            status: OK
            reason: OK
            sentTs: '2023-01-03T15:38:08Z'
            durationInSecs: 26
            sentToNumber: '004989123456789'
            remoteCsid: +49/89/1234567-89
          - number: '+4989123456790'
            faxID: FNIJPNJYNA06EDIJNFUO2Q
            properties:
              - key: FromName
                value: Jane Doe
              - key: ToName
                value: John Doe
            status: OK
            reason: OK
            sentTs: '2023-01-03T15:38:08Z'
            durationInSecs: 26
            sentToNumber: '004989123456790'
            remoteCsid: John Doe
        documents:
          - name: document1.pdf
            isText: false
            charset: UTF-8
          - name: document2.pdf
            isText: false
            charset: UTF-8
        options:
          resolution: HIGH
          tsid: Example Inc.
          header: Fax from %C to %#%r%Y-%m-%d
          isBlacklistEnabled: false
          isExpress: true
          overlay:
            name: overlay_template1
            mode: ALL_PAGES
          coverpageTemplateName: my_coverpage
          jobExpiryMinutes: 50
          billingCode: My BC 123
          billingInfo: Default billing code
          jobReference: My Reference ID
        pages: 2
