Definition

A Fax is a document that you want to send to one or more recipients using the Fax.Plus system. Faxes can be in various formats such as PDF, Word, Excel, and other common file types.

Key Concepts

Sending a Fax

When sending a fax, you typically need to provide:

  1. The recipient’s fax number(s)
  2. The document(s) you want to send
  3. Any additional options (e.g., cover page, scheduling)

Receiving a Fax

Fax.Plus can also receive faxes on your behalf. Received faxes are typically stored in your account and can be accessed through the API or web interface.

File Formats

Fax.Plus supports a wide range of file formats, including:

  • Documents: DOC, DOCX, PDF, TXT, RTF
  • Images: JPG, PNG, TIFF
  • Spreadsheets: XLS, XLSX

You can upload up to 10 different files per fax, regardless of the number of pages in each file. The maximum file size per upload is 30 MB.

Fax Status

After sending a fax, you can track its status. The status indicates whether the fax was successfully sent, is still in progress, or encountered an error. You can use webhooks to receive real-time updates on fax transmission status.

Fax Error Statuses

Fax.Plus uses a variety of error status codes to indicate the current state of a fax. Here are the possible statuses and their meanings:

StatusDescription
successThe fax was successfully sent.
partially_sentThe first pages were transmitted, but the call dropped due to connection issues.
partially_receivedThe first pages were received, but the call dropped due to connection issues.
insufficient_creditNot enough credit to send or receive pages. Add credit or wait for plan reset.
failedGeneric error. Retry, and contact support if the issue persists.
failed_internal_process_errorGeneric error. Retry, and contact support if the issue persists.
failed_user_busyThe destination was busy. Wait and retry.
failed_no_answerNo answer at the destination. Retry when you know the recipient is available.
failed_unallocated_numberInvalid number. Check the number, including country and area codes.
failed_office_converter_issueFailed to convert Microsoft Office document. Recreate and resubmit the file.
failed_separate_file_pages_issueFile conversion issue. Check if all pages in the source file(s) are valid.
failed_render_header_issueFile conversion issue. Check if all pages in the source file(s) are valid.
failed_invalid_number_formatInvalid number format. Check the number, including country and area codes.
failed_mimetype_not_supportedUnsupported file type.
failed_destination_not_supportedNumber is a special service number or not supported by your plan.
failed_image_preparationFile conversion issue. Check if all pages in the source file(s) are valid.
failed_to_sendSystem was busy. Try again later.
failed_normal_temporary_failureTemporary network issue. Retry immediately.
failed_unknown_converter_issueFile conversion failed. Check if the file is password-protected.
failed_normal_clearingDestination was busy. Wait and retry.
failed_convert_to_tiff_issueFile conversion issue. Check if all pages in the source file(s) are valid.
failed_fs_49Remote fax machine disconnected unexpectedly. Some pages may have been transmitted.

Best Practices

  1. File Preparation: Ensure your files are not corrupted or password-protected before sending.
  2. Number Verification: Double-check fax numbers, including country and area codes.
  3. Retry Strategy: For temporary failures, implement a retry mechanism with appropriate intervals.

Schema

comment
string
required

Free-form comment

cost
integer

Fax cost in the user currency

cost_details
object
required
description
string
direction
enum<string>

Fax direction

Available options:
outgoing,
incoming
duration
integer
file
string

Fax file ID for the getFile handle

file_name
string

Human-readable file name

from
string

Sender number. Might be a userId for faxes sent or received with free accounts

header
string
id
string
required

Fax ID

is_read
boolean
is_spam
boolean

True if the fax is marked as spam

last_update
string
max_retry
integer

Maximum number of retries

owner_id
string
required

User ID of the fax owner

pages
integer
required

Number of pages in the fax

retry_delay
integer

Delay between two retries

scheduled_time
string
start_time
string

Time at which faxing session started. Format: YYYY-MM-DD HH:mm:ss

status
enum<string>
required

Fax status

Available options:
success,
partially_sent,
partially_received,
insufficient_credit,
failed,
failed_internal_process_error,
failed_user_busy,
failed_no_answer,
failed_unallocated_number,
failed_office_converter_issue,
failed_separate_file_pages_issue,
failed_render_header_issue,
failed_invalid_number_format,
failed_mimetype_not_supported,
failed_destination_not_supported,
failed_image_preparation,
failed_to_send,
failed_normal_temporary_failure,
failed_unknown_converter_issue,
failed_normal_clearing,
failed_convert_to_tiff_issue,
failed_fs_49,
failed_fs_2
submit_time
string

Time when the fax was submitted for sending. For outgoing faxes only

to
string

Fax destination number. Might be a userId for faxes sent or received with free accounts

cover_page
object

Fax cover page