Definitions

reports
optional

< BulkJobReportResponseBodyItem > array

deleted
optional

Information on whether the job report could be deleted. Only present for responses to a bulk DELETE.

 boolean

jobId
required

The Job ID.

 string

pages
optional

Number of pages in the fax.

Only present for responses to a bulk GET.

 integer

reason
optional

Missing if deletion was successful, otherwise one of the following reason messages is returned:

• NOT_FOUND: No report exists for the given job id.

• INTERNAL_ERROR: Unspecified server-side error. Only present for responses to a bulk DELETE.

boolean

recipientStatus
optional

Fax recipient and status information.

Only present for responses to a bulk GET.

<FaxRecipientWithStatus> array

reference
optional

Only present for responses to a bulk GET.

 Reference

action
required

Defines the action to be performed on all jobs whose Job ID is provided in the jobIds list

Possible options are:

• DELETE: Bulk delete the requested jobs

• GET: Bulk get the requested jobs. Both options are case-insensitive.

string

jobIds
required

List of Job IDs to be processed in bulk

< string > array

Name

Description

Schema

charset
optional

Character encoding of plain text documents (*.txt). Possible values:

• US-ASCII

• UTF-8

• UTF-16

• UTF-16BE

• UTF-16LE

• ISO-8859-1

• Windows-1252
  Default : "UTF-8"

string

data
optional

base64 string with data, if no reference is provided. If both are provided, the reference data (see above) is used.

Example                                                                            :

"SGVsbG8sIHRoaXMgaXMgYSB0ZXN0aW5nIGRvY3VtZW50IGJvZHkgY 3JlYXRlZCBmb3IgOTk5OTlURQ=="

string

name
required

Document file name.

The file extension is important for determining the file type, e.g., Invoice-2017-01.pdf.

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"

string

reference
optional

A URL pointing to the document to be transmitted.

Example
"http://mydomain.retarus.com/my- path/mydocument.pdf"

string

documents
optional

<DocumentWithData> array

meta
optional

MetaData

recipients
required

< FaxRecipient > array

reference
optional

Reference

renderingOptions
optional

RenderingOptions

statusReportOptions
optional

StatusReportOptions

transportOptions
optional

TransportOptions

jobId
required

string

number
required

Dialed number (international format, e.g., +12015551000).

Example
"0012012051598"

string

properties
optional

Personalized data for the cover page.

<RecipientProperty> array

durationInSecs
required

Duration of the fax transmission until received by the fax recipient.

integer

number
required

The fax recipient’s primary number (international format, e.g., +49891234678).

string

properties
optional

Personalized data used for the cover page.

<RecipientProperty> array

reason
required

Explanation of the status.

string

remoteCsid
optional

Fax ID, which identifies the fax recipient.

string

sentToNumber
optional

Number to which the fax was sent.

string

sentTs
optional

Timestamp indicates when the fax was sent (in ISO 8601 format).

string (date-time)

status
required

Job status.

See Transmission status codes - Outbound Fax for details.

string

jobId
required

The Job ID.

string

pages
required

Number of pages in the fax.

integer

recipientStatus
required

<FaxRecipientWithStatus> array

reference
optional

Reference

reports
required

<FaxReport> array

authMethod
optional

Authentication method. Possible values are:

• HTTP_BASIC

• HTTP_DIGEST

• OAUTH2

• NONE
  Default : "NONE"

string

credentials
optional

The credential for the principal/username.

Example
"none"

string

principal
optional

The principal/user name.

Example
"none"

string

targetUrl
required

Push URL.

Example
"http://retarus.com/test-path/test-target"

string

deleted
required

Returns true if the job was successfully deleted, false otherwise. If absent in the response it means the job was successfully deleted.

boolean

jobId
required

The Job ID.

string

reason
optional

Missing if deletion was successful. Otherwise, one of the following reason messages is returned:

• NOT_FOUND: No report exists for the given job id.

• INTERNAL_ERROR: Unspecified server-side error.

string

end
optional

End of validity for the job (in ISO 8601 format).

Durations are also supported. The following values are all valid expiration times:

• 2018-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.

string (date-time)

start
optional

Beginning of validity for the job (in ISO 8601 format).

If this time is not defined correctly, you will receive a Job Expiration error. Example values are "Z" for UTC or -05:00 for EST.

By default, jobs are immediately valid.

string (date-time)

Name

Description

Schema

customerRefe rence

required

Information that the customer can use for internal references.

Example : "99999TE"

string

jobValid

optional

JobValid

mode
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 have an overlay in this mode)

string

name
required

Template name, without the path information and file extension.

Example
"overlay_template1"

string

key
required

Name of the key.

Example
"key123"

string

value
required

The value assigned to the key.

Example
"value123"

string

billingCode
optional

Information on the cost center; the format is arbitrary (max. 80 characters).

Example
"2018-08-7T11:04:37.057Z_billingCode"

string

billingInfo
optional

Additional data for internal customer accounting (max. 80 characters).

Example
"2018-08-7T11:04:37.057Z_billingInfo"

string

customerDefinedId optional

Freely-defined ID string (max. 256 characters).

Example
"2018-08-7T11:04:37.057Z_customerDefinedId"

string

coverpageTemplate
optional

The name of the cover page’s template; e.g., coverpage- default.ftl.html. If an empty string is used, no coverpage will be applied, even if a default coverpage is set in EAS. Example
"coverpage-default.ftl.html"

string

header
optional

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

string

overlay
optional

Overlay

paperFormat
required

The size of the paper. Possible options are:

• A4

• LETTER

string

resolution
optional

The fax’s resolution. Possible values are:

• LOW

• HIGH

string

attachedFaxImageFormat optional

Determines when 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 atached as PDF

• PDF_WITH_OCR: Fax image is ttached as a searchable PDF file. Additional costs may occur
  Default: "TIFF"

string

attachedFaxImageMode optional

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
  Default: "NEVER"
  Example: "SUCCESS_ONLY"

string

failureAddress
optional

Email address to which a notification should be sent when errors occur.

Example
"jane.doe@retarus.com"

string

successAddress
optional

Email address to which delivery confirmation notifications should be sent.

Example
"john.doe@retarus.com"

string

httpStatusPush
optional

HttpStatusPush

reportMail
optional

ReportMail

reportPurgeTs
required

Not currently valid. The date after which the status report is no longer available. In ISO 8601 format

Example
"2018-11-03T20:14:37.098+02:00"

string (date-time)

csid
optional

The sender ID that is displayed to the recipient of the fax. (max. 20 characters).

Example
"test-csid"

string

isBlacklistEnabled
optional

Flag for the use of the Robinson List (only for numbers in Germany), ECOFAX (for numbers in France), or Retarus' own blocklist.

boolean

isExpress
optional

Flag for transmissions sent express.

boolean