# 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: v1
Security: httpBasicAuth

## Path parameters:

  - `topic` (string, required)
    Topic to be polled

## Query parameters:

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

  - `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.

  - `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)

  - `meta.next` (string)

  - `meta.exit` (string)

  - `meta.topic` (string)

  - `meta.resultSize` (integer)

  - `meta.parameters` (object)

  - `meta.parameters.fetch` (integer)

  - `meta.parameters.timeout` (integer)

  - `meta.parameters.ids` (array)

  - `results` (array, required)

  - `results.id` (string)

  - `results.callId` (string)

  - `results.costCenter` (string)

  - `results.dateReceived` (string)

  - `results.totalDuration` (integer)

  - `results.senderIsdn` (string)

  - `results.senderFaxId` (string)

  - `results.receiverIsdn` (string)

  - `results.receiverFaxId` (string)

  - `results.faxResolution` (string)

  - `results.faxBaudRate` (integer)

  - `results.faxPageCount` (integer)

  - `results.faxClassicStatus` (string)

  - `results.faxNumericStatus` (string)

  - `results.archivingStatus` (string)

  - `results.archiveExpiry` (string)

  - `results.documents` (array)

  - `results.documents.url` (string, required)

  - `results.documents.type` (string, required)