Hoiio Open API logo Hoiio Open API

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:

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.