Send Fax

Definition

https://secure.hoiio.com/open/fax/send

Parameters

app_id*	string Application ID assigned to your application.
access_token*	string Access Token assigned to your application.
dest*	string The destination to send the fax to. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111.
file*	string The file to be faxed in Base64 format. We also allow uploading the file directly using multipart/form-data. The file must be in PDF format with a page size of either A4 or Letter and its file size can be at most 2MB.
filename	string The name of the file that is downloaded from the fax_url given in fax/query_status and fax/get_history.
caller_id	string This is the Caller ID that the receiver will see on their incoming call. Possible values are: your registered number, your Hoiio Number, "private". Numbers should start with a "+" and country code (E.164 format), e.g. +6511111111. If omitted, your registered number will be used as Caller ID.
fax_header	string This is the header that will be printed along the short edge of each page. If this parameter is not provided, the default header "Fax from caller_id at dest was received" will be printed instead. If an empty parameter is provided, no header will be displayed for this fax. The header should contain only alphanumeric characters, and spaces. It should have a max size of 100 characters.
tag	string This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
notify_url	string A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution. The length of this parameter must not exceed 4000 characters. See Controlling IVR Behavior for more details. If omitted, the call will hang up after msg is played, and the notification will not be sent to you.

Examples

cURL: application/x-www-form-urlencoded

curl https://secure.hoiio.com/open/fax/send \
-d app_id=YOUR_APP_ID \
-d access_token=YOUR_ACCESS_TOKEN \
--data-urlencode dest=+6512345678 \
--data-urlencode file="`base64 fax.pdf`"

cURL: multipart/form-data

curl https://secure.hoiio.com/open/fax/send \
-F app_id=YOUR_APP_ID \
-F access_token=YOUR_ACCESS_TOKEN \
-F dest=+6512345678 \
-F file=@fax.pdf

Result Format

{"txn_ref":"AA-C-141147","status":"success_ok"}

Documentation

This API will send a fax file to a fax number.

Note that Fax is only supported in the following countries:

Singapore
Hong Kong
Malaysia

Response Parameters

status	The result of your request. Refer to Result Status for details.
txn_ref	A unique reference ID for this fax transaction. This parameter will not be present if the request was not successful.

Result Status

success_ok	The request has been processed successfully.
error_invalid_http_method	Invalid HTTP method. Only GET or POST are allowed.
error_malformed_params	HTTP POST request parameters contains non-readable bytes.
error_X_param_missing	A required parameter is missing. X is the name of the parameter that is missing.
error_invalid_access_token	Your Access Token is invalid, expired or has been revoked.
error_invalid_app_id	Your Application ID is invalid or has been revoked.
error_tag_invalid_length	`tag` parameter is too long, must be 256 characters or less.
error_service_not_available	The fax service is currently not available to the destination you specified. Do check at our Pricing Page to see the destinations supported.
error_destination_not_supported	`dest` is not supported for fax.
error_invalid_destination	`dest` is invalid.
error_invalid_notify_url	Invalid URL in `notify_url` parameter.
error_unable_to_resolve_notify_url	Cannot resolve URL in `notify_url` parameter.
error_insufficient_credit	You have insufficient credit in your developer account to make this call.
error_file_too_big	The file you are uploading exceeds 2MB.
error_file_invalid	`file` is not a PDF file.
error_page_size_invalid	file` contains pages that are neither A4 nor Letter size.
error_fax_header_invalid	`fax_header` contains non-alphanumeric characters, or exceeds the 100 character limit.
error_rate_limit_exceeded	You have exceeded your request limit for this API. Refer to API Limits for details.
error_internal_server_error	There is an unexpected error. Please contact Hoiio support for assistance.

Sample Request:

Using application/x-www-form-urlencoded content type

 curl https://secure.hoiio.com/open/fax/send \
-d app_id=YOUR_APP_ID \
-d access_token=YOUR_ACCESS_TOKEN \
--data-urlencode dest=+6512345678 \
--data-urlencode file="`base64 fax.pdf`"

Note that we have to first convert fax.pdf to a base64 encoded string using the base64 utility.

Using multipart/form-data content type

curl https://secure.hoiio.com/open/fax/send \
-F app_id=YOUR_APP_ID \
-F access_token=YOUR_ACCESS_TOKEN \
-F dest=+6512345678 \
-F file=@fax.pdf

Note that when using multipart/form-data we do NOT need to perform base64 encoding.

Notifications

To check on the status of the fax, you can include the notify_url parameter. If the notify_url parameter was included in your original API request, a notification will be sent to the URL you specified when the fax has sent with the following parameters:

Notification Parameters

txn_ref	The unique reference ID for this transaction.
dest	The number you sent the fax to. Phone numbers start with a \"+\" and country code ([E.164](https://en.wikipedia.org/wiki/E.164) format), e.g. +6511111111.
fax_status	Status of the incoming fax. Possible values are: answered unanswered failed busy
date	Date/time (GMT+8) of this transaction in "YYYY-MM-DD HH:mm:SS" format.
duration	Duration of the call in minutes.
currency	Currency used for this transaction. Refer to Currency Code for the list of currency code.
debit	Total amount billed for this transaction.
fax_error_code	This parameter provides additional details when a fax fails. It will only be provided if a fax is unsuccessful. It is also not be provided for faxes which are still "ongoing". Values pertaining to Outgoing/Incoming Faxes: busy - The fax number dialed was busy, and the fax could not be initiated. non_recoverable - The fax has failed due to problems connecting to the other fax machine. This can be due to poor line quality, and incompatibilities between the fax systems. If this occurs on an Incoming Fax, please ask the sender to retry with an IDD call, instead of a budget, or VoIP service. cannot_establish_transmission - The fax has failed due to problems dialing to the other fax machine. Please check that the destination number is valid. Values pertaining to Incoming Faxes: invalid_res - A suitable fax resolution could not be established for the fax transfer. Please check with the sender on reducing the resolution setting on their fax machine, and try again. invalid_size - The fax being received was not of a suitable paper format size. We support only A4 and Letter paper formats. Please check with the sender that the page size setting is set correctly on their fax machine, and try again. Values pertaining to Outgoing Faxes: file_err - There were problems converting your PDF into a faxable format. Ideally, your PDF should comply with the PDF/A standard.
fax_pages	The number of pages faxed.
rate	Per-page charges for this fax transaction.
tag	Your own reference ID submitted in the initial [fax/send request](doc:send-fax#request-parameters). This parameter will not be present if it wasn't included in the initial request.

API Limits

Maximum of 8 active faxes per application at any point of time

Charges

Charges apply for faxes successfully connected via this API. Faxes are charged based on destination.