openapi: 3.0.3
info:
  title: Fax2WSPull
  version: v0
  description: >
    Fax2WSPull allows clients to actively retrieve faxes received 

    for you via the Retarus cloud-based infrastructure instead of passively 

    waiting for them to be delivered to a web service. The unit of organization
    for this 

    process is the **topic**. A topic represents one or more fax numbers that
    are used to 

    receive faxes.


    For each topic, the API provides information about received faxes, 

    including the URL to the fax documents itself. 


    Every inbound document showed as available is hidden after retrieval.
    However, fax

    receipt should be acknowledged by the client in the retrieval process. If

    this doesn't happen within a pre-defined timeout period, the document is

    made available again, assuming that there was some issue with the

    application during the retrieval process.


    Each request or response in this document is JSON serialized and encoded

    using the **UTF-8** character set.


    The fax documents themselves are automatically deleted **7 days** after
    receipt by default, 

    regardless of whether they were downloaded or not.
  contact:
    name: Retarus
    url: https://www.retarus.com/
    email: info@retarus.com
  termsOfService: https://www.retarus.com/us/legal-disclaimer/
servers:
  - url: https://api.de1.retarus.com/faxin/rest/v1
    description: Retarus data center in Frankfurt, Germany
  - url: https://api.de2.retarus.com/faxin/rest/v1
    description: Retarus data center in Munich, Germany
  - url: https://api.us1.retarus.com/faxin/rest/v1
    description: Retarus data center in Ashburn, United States
  - url: https://api.us2.retarus.com/faxin/rest/v1
    description: Retarus data center in Secaucus, United States
  - url: https://api.ch1.retarus.com/faxin/rest/v1
    description: Retarus data center in Zurich, Switzerland
  - url: https://api.sg1.retarus.com/faxin/rest/v1
    description: Retarus data center in Singapore
paths:
  /topics/{topic}:
    post:
      tags:
        - Fax2WSPull Client
      summary: Retrieve fax jobs from a topic and confirm the receipt.
      description: >
        This endpoint is used for two types of processes:   


        On the one hand, you can retrieve a list of unlocked and
        non-acknowledged fax jobs 

        from a topic owned by the authenticated user. The amount of fetched
        faxes is limited 

        by the `fetch` parameter. On the other hand, you should acknowledge
        faxes that you 

        successfully received by specifying an URL-encoded list of fax job ids.


        You retrieve the list of available faxes for a topic via a `POST`
        request to the 

        corresponding URL. The response consists of two parts: `meta` and
        `results`. 



        The  `meta` part contains information about the request

        and two URLs that the client should call after retreiving the jobs,

        the `next` URL or the `exit` URL. Retrieving the faxes themselves is
        described in the 

        `GET` operation below.


        The `next` URL is used to retrieve an additional batch of available
        faxes. The 

        request also confirms that the previous jobs were successfully retrieved
        by the 

        client through the `ids` parameter. 


        The `exit` URL is just another call to the same URL with the

        `fetch` parameter set to 0. It is used to confirm the reception of

        the previous jobs without retreiving information about new ones, for
        example in 

        case a shutdown of the client is requested. 


        The response to the `next` and `exit` URLs has the identical 

        structure and function as the ones described here.



        The `results` part contains information about the available fax

        jobs. This includes both the metadata for the fax and the transmission
        and the

        URLs from which the client can retrieve the fax images.
      operationId: pollFaxInformation
      parameters:
        - name: topic
          in: path
          required: true
          description: Topic to be polled
          schema:
            type: string
            example: abc123
        - name: fetch
          in: query
          required: false
          description: >-
            Number of fax jobs requested by the customer to be fetched from the
            topic
          schema:
            type: integer
            example: 10
        - name: ids
          in: query
          required: false
          description: >
            List of fax job ids to be acknowledged in this request. It must be
            comma-separated and

            presented in URL encoding, e.g. 365%2C366%2C367%2C368.
          schema:
            type: string
            example: 365%2C366%2C367%2C368
        - name: timeout
          in: query
          required: false
          description: >
            Lock timeout in seconds for a fax (by default 60). Once the metadata
            for a

            fax has been provided to a client, it will be marked as "locked" and
            not be

            returned again in subsequent requests. If the timeout expires
            without the

            client having acknowledged the correct receipt, the server will
            assume

            that a problem has occurred and it will make the fax available again
            in the

            next response.
          schema:
            type: integer
            default: 60
      security:
        - httpBasicAuth: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopicContents'
              examples:
                twoFaxes:
                  $ref: '#/components/examples/TopicContents'
                ConfirmFax:
                  $ref: '#/components/examples/ConfirmFax'
        '401':
          description: Forbidden. Authentication information is missing or invalid
        '403':
          description: >-
            Unauthorized acess. The authenticated user has no permission to
            fetch from the specified topic.
  /files/{id}.{extension}:
    get:
      tags:
        - Fax2WSPull Client
      summary: Download file by  file name (Id.Extension)
      description: |
        Download file by  file name (Id.Extension)
      operationId: pollFaxDocuments
      parameters:
        - name: id
          in: path
          required: true
          description: File Id to be downloaded
          schema:
            type: string
        - name: extension
          in: path
          required: true
          description: Extension of the file to be downloaded
          schema:
            type: string
      responses:
        '200':
          description: OK
        '401':
          description: Authentication information is missing or invalid
      security:
        - httpBasicAuth: []
components:
  schemas:
    TopicContents:
      type: object
      required:
        - meta
        - results
      properties:
        meta:
          $ref: '#/components/schemas/meta'
        results:
          type: array
          items:
            $ref: '#/components/schemas/results'
    meta:
      type: object
      properties:
        version:
          type: integer
          example: 1
        next:
          type: string
          example: >-
            https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=10&timeout=60&ids=29%2C30
        exit:
          type: string
          example: >-
            https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=0&timeout=60&ids=29%2C30
        topic:
          type: string
          example: abc123
        resultSize:
          type: integer
          example: 2
        parameters:
          $ref: '#/components/schemas/parameters'
    parameters:
      type: object
      properties:
        fetch:
          type: integer
          example: 10
        timeout:
          type: integer
          example: 60
        ids:
          type: array
          items:
            $ref: '#/components/schemas/id'
    id:
      type: string
      example: '10001234'
    results:
      type: array
      items:
        $ref: '#/components/schemas/result'
    result:
      type: object
      properties:
        id:
          type: string
          example: '29'
        callId:
          type: string
          example: J5WA4IAA@BXATD0S.glagqaseq108.DC2
        costCenter:
          type: string
          example: my billing code
        dateReceived:
          type: string
          example: 2023-08-03T12:09:43+0200
        totalDuration:
          type: integer
          example: 82
        senderIsdn:
          type: string
          example: '00498912345678'
        senderFaxId:
          type: string
          example: Retarus/Doe
        receiverIsdn:
          type: string
          example: '+4989262080440'
        receiverFaxId:
          type: string
          example: Retarus Faxolution
        faxResolution:
          type: string
          example: HIGH
        faxBaudRate:
          type: integer
          example: 33600
        faxPageCount:
          type: integer
          example: 1
        faxClassicStatus:
          type: string
          example: OK
        faxNumericStatus:
          type: string
          example: 2.0.0
        archivingStatus:
          type: string
          example: SUCCEEDED
        archiveExpiry:
          type: string
          example: 2023.08.10
        documents:
          type: array
          items:
            $ref: '#/components/schemas/documents'
    documents:
      type: array
      items:
        type: object
        required:
          - url
          - type
        properties:
          url:
            type: string
            example: https://api.us1.retarus.com/faxin/rest/v1/files/20.tif
          type:
            type: string
            example: image/tiff
  examples:
    TopicContents:
      summary: Retrieve polling information
      value:
        meta:
          version: 1
          next: >-
            https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=10&timeout=60&ids=29%2C30
          exit: >-
            https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=0&timeout=60&ids=29%2C30
          topic: abc123
          resultSize: 2
          parameters:
            fetch: 10
            timeout: 60
            ids: []
        results:
          - id: '29'
            callId: J5WA4IAA@BXATD0S.glagqaseq108.DC2
            costCenter: my billing code
            dateReceived: 2023-08-03T12:09:13+0200
            totalDuration: 23
            senderIsdn: '00498912345678'
            senderFaxId: Retarus/Doe
            receiverIsdn: '+4989262080440'
            receiverFaxId: Retarus Faxolution
            faxResolution: HIGH
            faxBaudRate: 33600
            faxPageCount: 1
            faxClassicStatus: OK
            faxNumericStatus: 2.0.0
            archivingStatus: NOT_CONFIGURED
            archiveExpiry: ''
            documents:
              - url: https://api.us1.retarus.com/faxin/rest/v1/files/20.tif
                type: image/tiff
          - id: '30'
            callId: J5WA55PT@CXEFXVG.glagqaseq109.DC2
            costCenter: my billing code
            dateReceived: 2023-08-03T12:09:43+0200
            totalDuration: 42
            senderIsdn: '00498912345678'
            senderFaxId: Retarus/Doe
            receiverIsdn: '+4989262080440'
            receiverFaxId: Retarus Faxolution
            faxResolution: HIGH
            faxBaudRate: 26400
            faxPageCount: 1
            faxClassicStatus: OK
            faxNumericStatus: 2.0.0
            archivingStatus: NOT_CONFIGURED
            archiveExpiry: ''
            documents:
              - url: https://api.us1.retarus.com/faxin/rest/v1/files/21.pdf
                type: application/pdf
    ConfirmFax:
      summary: Confirm a fax
      value:
        meta:
          version: 1
          next: >-
            https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=10&timeout=60&ids=29%2C30
          exit: >-
            https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=0&timeout=60&ids=29%2C30
          topic: abc123
          resultSize: 0
          parameters:
            fetch: 0
            timeout: 60
            ids:
              - '30'
        results: []
  securitySchemes:
    httpBasicAuth:
      type: http
      description: >
        The format is `<Retarus Customer Number>:<Password>`, encoded via Base
        64.

        The passwords are provided by Retarus and they can be associated to one
        or more incoming telephone numbers.

        As for example:

        ```

        Authorization: Basic OTk5OTk6S0tkUVNHSU1XME1mOTdiVA==

        ```

        Multiple processes can be operated concurrently by the Webservice using
        the same 

        password or multiple passwords.
      scheme: basic
