# List faxes

List faxes sent (OUTBOUND) or received (INBOUND), set parameters to filter the list.
Example: Return calls made between 1st of January 2021 and  10th of January 2021.

 created>=2021-01-01&startTime<=2021-01-10

Endpoint: GET /faxes
Version: 3.0
Security: BasicAuth, OAuth2

## Query parameters:

  - `serviceId` (string)
    Limits results to faxes that were sent using the specified service.
    Example: "YOUR_SERVICE_ID"

  - `createTime` (string)
    Filter calls based on  createTime. If you make the query more precise, fewer results will be returned.
For example, 2021-02-01 will return all calls from the first of February 2021, and 2021-02-01T14:00:00Z will return all calls after 14:00 on the first of February.
This field also supports = to search for calls in a range ?createTime>=2021-10-01&startTime<=2021-10-30 to get a list of calls for all of October 2021.
It is also possible to submit partial dates. For example, createTime=2021-02 will return all calls for February 2021.

If not value is submitted, the default value is the prior week.

  - `direction` (string)
    Limits results to faxes with the specified direction.
    Enum: "OUTBOUND", "INBOUND"

  - `status` (string)
    Limits results to faxes with the specified status.
    Enum: "QUEUED", "IN_PROGRESS", "COMPLETED", "FAILURE"

  - `to` (string)
    A phone number that you want to use to filter results. The parameter search with startsWith, so you can pass a partial number to get all faxes sent to numbers that start with the number you passed.
    Example: "+15551235656"

  - `from` (string)
    A phone number that you want to use to filter results.  The parameter search with startsWith, so you can pass a partial number to get all faxes sent to numbers that start with the number you passed.
    Example: "+15551235656"

  - `pageSize` (integer)
    The maximum number of items to return per request. The default is 100 and the maximum is 1000. If you need to export larger amounts and pagination is not suitable for you can use the Export function in the dashboard.

  - `page` (string)
    The page you want to retrieve returned from a previous List request, if any

## Response 200 fields (application/json):

  - `faxes` (array)
    An array of faxes

  - `faxes.id` (string)
    The id of a fax
    Example: "01F3J0G1M4WQR6HGY6HCF6JA0K"

  - `faxes.direction` (string)
    The direction of the fax.
    Enum: "OUTBOUND", "INBOUND"

  - `faxes.from` (string)
    For INBOUND faxes, this is the number where the fax is sent from
For OUTBOUND faxes, this is the Sinch number you want to have as sender
    Example: "+15551235656"

  - `faxes.to` (string)
    For INBOUND faxes, this is the Sinch number someone sent the fax to.
For OUTBOUND faxes, this is the phone number you want to send a fax to.

You can add multiple numbers by adding them as an array. For example:

  application/json

  json
  "to": ["+14155552222", "+14155553333"]
  

  multipart/form
  json
  to=+14155552222&to=+14155553333
    Example: "+15551235656"

  - `faxes.numberOfPages` (integer)
    The number of pages in the fax.

  - `faxes.status` (string)
    The status of the fax
    Enum: "QUEUED", "IN_PROGRESS", "COMPLETED", "FAILURE"

  - `faxes.price` (object)
    The total price for this fax. This field is populated after the final fax price is calculated.

  - `faxes.price.currencyCode` (string)
    The 3-letter currency code defined in ISO 4217.
    Example: "USD"

  - `faxes.price.amount` (string)
    The amount with 4 decimals and decimal delimiter ..
    Example: "0.0040"

  - `faxes.barCodes` (array)
    The bar codes found in the fax. This field is populated when Sinch detects bar codes on incoming faxes.

  - `faxes.barCodes.type` (string)
    The type of barcode found.
    Enum: "CODE_128", "DATA_MATRIX"

  - `faxes.barCodes.page` (integer)
    The page number on which the barcode was found.

  - `faxes.barCodes.value` (string)
    The  information of the barcode.

  - `faxes.createTime` (string)
    A timestamp representing the time when the initial API call was made.

  - `faxes.completedTime` (string)
    If the job is complete, this is a timestamp representing the time the job was completed.

  - `faxes.pagesSentSuccessfully` (integer)
    The number of pages successfully sent to the receiving side in the fax.
    Example: 3

  - `faxes.headerText` (string)
    Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails.

  - `faxes.headerPageNumbers` (boolean)
    If true, page numbers will be displayed in the header. Default is true.

  - `faxes.headerTimeZone` (string)
    A [TZ database name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) string specifying the timezone for the header timestamp.

  - `faxes.retryDelaySeconds` (integer)
    The number of seconds to wait between retries if the fax is not yet completed.

  - `faxes.labels` (object)
    You can use this to attach labels to your call that you can use in your BI solutions.
    Example: {"use-case":"fraudPrevention","costCenter":"sales"}

  - `faxes.callbackUrl` (string)
    The URL to which a callback will be sent when the fax is completed. The callback will be sent as a POST request with a JSON body. The callback will be sent to the URL specified in the callbackUrl parameter, if provided, otherwise it will be sent to the URL specified in the callbackUrl field of the Fax Service object.
    Example: "https://www.my-website.com/callback"

  - `faxes.callbackUrlContentType` (string)
    The content type of the callback.
    Enum: "multipart/form-data", "application/json"

  - `faxes.imageConversionMethod` (string)
    Determines how documents are converted to black and white on OUTBOUND faxes only.  Image conversion is not done on INBOUND faxes. Defaults to value selected on Fax Service object.
    Enum: "HALFTONE", "MONOCHROME"

  - `faxes.errorType` (string)
    Error type
    Enum: "DOCUMENT_CONVERSION_ERROR", "CALL_ERROR", "FAX_ERROR", "FATAL_ERROR", "GENERAL_ERROR"

  - `faxes.errorCode` (integer)
    One of the error numbers listed in the [Fax Error Messages section](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages).

  - `faxes.errorMessage` (string)
    One of the error codes listed in the [Fax Error Messages section](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages).

  - `faxes.maxRetries` (integer)
    | The number of times the fax will be retired before cancel. Default value is set in your fax service.
| The maximum number of retries is 5.

  - `faxes.retryCount` (integer)
    The number of times the fax has been retried.

  - `faxes.hasFile` (string)
    Only shown on the fax result. This indicates if the content of the fax is stored with Sinch. (true or false)

  - `faxes.resolution` (string)
    The resolution for the fax. If this is set at the service, this applies to all faxes sent using that service. If this is set on the fax, this will override the service setting.
    Enum: "FINE", "SUPERFINE"

  - `faxes.coverPageId` (string)
    The cover page id you want to use for the fax

  - `faxes.coverPageData` (object)
    You can use this to specify custom data for your cover page that will be sent as part of the fax. It is a key value store. Read more about how to use this [here](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/). All keys used must be lower case.

- application/json format: "coverPageData": {"customfield1":"customdata1"}
- multipart/form-data format: coverPageData[customfield1] = customdata1

  - `faxes.inProgressNotifications` (boolean)
    If set to true, you will receive a webhook notification for each page sent on an outbound fax.

  - `faxes.projectId` (string)
    The Id of the project associated with the call.
    Example: "ae00f005-e392-44dc-b3f5-a657a2684dg3"

  - `faxes.serviceId` (string)
    ID of the fax service used.
    Example: "01GVRB50KEQFFE1SGMPFRNBG6J"

  - `page` (integer)
    Current page

  - `totalPages` (integer)
    Total number of pages.

  - `pageSize` (integer)
    Number of items per page.

  - `totalItems` (integer)
    Total size of the result.