# Retrieve fax jobs from a topic and confirm the receipt.

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.

Endpoint: POST /topics/{topic}
Version: v0
Security: httpBasicAuth

## Path parameters:

  - `topic` (string, required)
    Topic to be polled
    Example: "abc123"

## Query parameters:

  - `fetch` (integer)
    Number of fax jobs requested by the customer to be fetched from the topic
    Example: 10

  - `ids` (string)
    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.
    Example: "365%2C366%2C367%2C368"

  - `timeout` (integer)
    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.

## Response 200 fields (application/json):

  - `meta` (object, required)

  - `meta.version` (integer)
    Example: 1

  - `meta.next` (string)
    Example: "https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=10&timeout=60&ids=29%2C30"

  - `meta.exit` (string)
    Example: "https://api.us1.retarus.com/faxin/rest/v1/topics/abc123?fetch=0&timeout=60&ids=29%2C30"

  - `meta.topic` (string)
    Example: "abc123"

  - `meta.resultSize` (integer)
    Example: 2

  - `meta.parameters` (object)

  - `meta.parameters.fetch` (integer)
    Example: 10

  - `meta.parameters.timeout` (integer)
    Example: 60

  - `meta.parameters.ids` (array)
    Example: ["10001234"]

  - `results` (array, required)

  - `results.id` (string)
    Example: "29"

  - `results.callId` (string)
    Example: "J5WA4IAA@BXATD0S.glagqaseq108.DC2"

  - `results.costCenter` (string)
    Example: "my billing code"

  - `results.dateReceived` (string)
    Example: "2023-08-03T12:09:43+0200"

  - `results.totalDuration` (integer)
    Example: 82

  - `results.senderIsdn` (string)
    Example: "00498912345678"

  - `results.senderFaxId` (string)
    Example: "Retarus/Doe"

  - `results.receiverIsdn` (string)
    Example: "+4989262080440"

  - `results.receiverFaxId` (string)
    Example: "Retarus Faxolution"

  - `results.faxResolution` (string)
    Example: "HIGH"

  - `results.faxBaudRate` (integer)
    Example: 33600

  - `results.faxPageCount` (integer)
    Example: 1

  - `results.faxClassicStatus` (string)
    Example: "OK"

  - `results.faxNumericStatus` (string)
    Example: "2.0.0"

  - `results.archivingStatus` (string)
    Example: "SUCCEEDED"

  - `results.archiveExpiry` (string)
    Example: "2023.08.10"

  - `results.documents` (array)

  - `results.documents.url` (string, required)
    Example: "https://api.us1.retarus.com/faxin/rest/v1/files/20.tif"

  - `results.documents.type` (string, required)
    Example: "image/tiff"


## Response 401 fields

## Response 403 fields