# Send a fax

This method is used to prepare fax jobs to be transferred for processing. If a valid FaxJobRequest has been received by the Webservice, the Webservice sends a Job ID back that must be specified by the client when querying the job status.

Endpoint: POST /{custNr}/fax
Version: v1
Security: httpBasicAuth

## Path parameters:

  - `custNr` (string, required)
    Your Retarus Customer Number (e.g. 99999TE).

## Request fields (application/json):

  - `reference` (object)

  - `reference.customerDefinedId` (string)
    Freely-defined ID string (max. 256 characters).
    Example: "2022-04-7T11:04:37.057Z_customerDefinedId"

  - `reference.billingCode` (string)
    Information on the cost center; format is arbitrary (max. 80 characters).
    Example: "2022-04-7T11:04:37.057Z_billingCode"

  - `reference.billingInfo` (string)
    Additional data for internal customer accounting (max. 80 characters).
    Example: "2022-04-7T11:04:37.057Z_billingInfo"

  - `recipients` (array, required)

  - `recipients.number` (string, required)
    Dialed number (international format, e.g., +12015551000).
    Example: "0012012051598"

  - `recipients.properties` (array)
    Personalized data for the cover page.

  - `recipients.properties.key` (string, required)
    Name of the key.
    Example: "key123"

  - `recipients.properties.value` (string, required)
    The value assigned to the key.
    Example: "value123"

  - `documents` (array)

  - `documents.name` (string, required)
    Document file name; the file extension is important for determining the file type, e.g., Invoice-2017-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"

  - `documents.charset` (string)
    Character encoding of plain text documents (*.txt). Possible values:

* US-ASCII
* UTF-8
* UTF-16
* UTF-16BE
* UTF-16LE
* ISO-8859-1
* Windows-1252

  - `documents.reference` (string,null)
    A URL pointing to the document to be transmitted.
    Example: "http://mydomain.retarus.com/my-path/mydocument.pdf"

  - `documents.data` (string,null)
    base64 string with data, if no reference is provided. If both are provided, the reference data (see above) is used.
    Example: "SGVsbG8sIHRoaXMgaXMgYSB0ZXN0aW5nIGRvY3VtZW50IGJvZHkgY3JlYXRlZCBmb3IgOTk5OTlURQ=="

  - `transportOptions` (object)
    Contains information on the transmission of the fax.

  - `transportOptions.csid` (string)
    The sender ID the received fax was sent from (max. 20 characters).
    Example: "test-csid"

  - `transportOptions.isExpress` (boolean)
    Flag for transmissions sent express.

  - `transportOptions.isBlacklistEnabled` (boolean)
    Flag for the use of the Robinson List (only for numbers in Germany),
ECOFAX (for numbers in France), or Retarus' own blacklist.

  - `renderingOptions` (object)
    Contains instructions for the rendering of the fax.

  - `renderingOptions.paperFormat` (string,null, required)
    The size of the paper. Possible options are:

* A4
* LETTER

  - `renderingOptions.resolution` (string)
    The fax's resolution. Possible values are:

  * LOW
  * HIGH

  - `renderingOptions.coverpageTemplate` (string)
    The name of the cover page's template; e.g., coverpage-default.ftl.html.
    Example: "coverpage-default.ftl.html"

  - `renderingOptions.overlay` (object,null)
    Settings for the overlay (e.g., stationery). An overlay (e.g., with letter
header and footer) can be applied to all or specific pages in the fax. It
consists of a one-page, black-and-white TIF image document. In order to
use an overlay, it must be deployed to the customer's account by a Retarus
technician. The customer can provide a document in various formats eg PDF,
which Retarus experts will then convert to a TIF image and deploy it using
an agreed upon name.

  - `renderingOptions.overlay.name` (string, required)
    The overlay name excluding the TIF file extension and without any path information.
    Example: "LetterHead"

  - `renderingOptions.overlay.mode` (string, required)
    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 receive an overlay in this mode)
    Enum: "ALL_PAGES", "NO_OVERLAY", "FIRST_PAGE", "LAST_PAGE", "ALL_BUT_FIRST_PAGE", "ALL_BUT_LAST_PAGE", "ALL_BUT_FIRST_AND_LAST_PAGE", "FIRST_FILE"

  - `renderingOptions.header` (string)
    the content of the header, including control characters.
    Example: "%tz=CEST Testfax: CSID: %C Recipient number: %# Date: %d.%m.%Y %H:%M %z"

  - `statusReportOptions` (object)
    settings for the status report. Consists of reportPurgeTs and reportMail.

  - `statusReportOptions.reportPurgeTs` (string)
    Not currently valid. The date after which the status report is no longer available. In ISO 8601 format
    Example: "2022-11-03T20:14:37.098+02:00"

  - `statusReportOptions.reportMail` (object)
    In addition to querying via Webservice, it is possible to request notification for each fax job as soon as processing is completed. The status information can be sent by either HTTP POST or email.
Separate email addresses can each be specified for delivery and failed delivery confirmations. If an email address is deleted for either type of confirmation, no notification email will be sent for the confirmation type that was removed.
The report emails' format is specified through a template which is filled out with relevant data (Job ID, job status, details on the fax recipients). A default template is available for all customers; however, you can install a customized template. Templates must be encoded in UTF-8 format.
In addition, it is possible to specify whether the fax image should be attached to the report or not and if so in which format

  - `statusReportOptions.reportMail.successAddress` (string)
    Email address, to which delivery confirmations notifications should be sent.
    Example: "john.doe@retarus.com"

  - `statusReportOptions.reportMail.failureAddress` (string)
    Email address, to which a notification should be sent when errors occur.
    Example: "jane.doe@retarus.com"

  - `statusReportOptions.reportMail.attachedFaxImageMode` (string)
    Determines when the fax image will be attached to the email. Possible values are:

  * NEVER: Never attach the fax image
  * SUCCESS_ONLY: Only attach the fax image in case of successful transmission
  * FAILURE_ONLY: Only attach the fax image in case of failed transmission
  * ALWAYS: Always attach the fax image
    Example: "SUCCESS_ONLY"

  - `statusReportOptions.reportMail.attachedFaxImageFormat` (string)
    Determines the format in which the fax image will be attached to the email. The following formats are supported:

  * TIFF: Fax image is attached as TIFF
  * PDF: Fax image is attached as PDF
  * PDF_WITH_OCR: Fax image is attached as a searchable PDF file. Additional costs may occur

  - `statusReportOptions.httpStatusPush` (object)
    In order to receive notification via HTTP, the JobRequest must contain
the httpStatusPush element. The URL to which the HTTP POST request is
sent has to be specified.

Please see the HTTP status push documentation for additional details.

  - `statusReportOptions.httpStatusPush.targetUrl` (string, required)
    The HTTP url to post the fax job status to (webhook). A default URL can be configured for the account.
    Example: "https://retarus.com/test-path/test-target"

  - `statusReportOptions.httpStatusPush.principal` (string,null)
    The user name to authenticate with the status push endpoint, if required. When using OAUTH2 this is the client id to obtain access tokens.
    Example: "none"

  - `statusReportOptions.httpStatusPush.credentials` (string,null)
    The password to authenticate with the status push endpoint, if required. When using OAUTH2 this is the client secret to obtain access tokens.
    Example: "none"

  - `statusReportOptions.httpStatusPush.authMethod` (string)
    The authentication method for the status push. Supported authentication methods and the corresponding values are:

  * HTTP_BASIC
  * HTTP_DIGEST
  * OAUTH2
  * NONE

In order to use OAUTH2, the authorization server URL must be configured in advance for the account.
    Enum: "HTTP_BASIC", "HTTP_DIGEST", "OAUTH2", "NONE"

  - `meta` (object)
    Meta information about the request.

  - `meta.jobValid` (object)
    Contains the valid start/end of a fax job (in ISO 8601 format). If this data
is not defined correctly, you will receive a Job Expiration error.

If you want to use the default values, simply ignore this object.

  - `meta.jobValid.start` (string,null)
    Beginning of validity for the job (in ISO 8601 format).
Please note: if this time is not defined correctly, you will receive a Job Expiration error. By default jobs are immediately valid.

  - `meta.jobValid.end` (string)
    End of validity for the job (in ISO 8601 format). Please note that also durations are supported; the following values are all valid expiration times:

* 2022-10-11T15:50:21.372Z (expiration set to the exact moment specified)
* PT80M  (Expiration set to now + 80 minutes)

By default jobs expire one month after they begin being valid.
The value must be one of these choices:
  * string with format "date-time"
  * string with format "duration"

## Response 200 fields (application/json):

  - `jobId` (string, required)
    Example: "FJKQQUVF1J0IADYARQEXKC"

## Response 400 fields (application/json):

  - `code` (integer)

  - `message` (string)

## Response 401 fields (application/json):

  - `code` (integer)
    Example: 401

  - `message` (string)
    Example: "Authentication failed"


## Response 429 fields