To receive an incoming fax, you’ll need to subscribe to a Hoiio Number. After you have subscribed to a Hoiio Number, you must configure your number to send a notification to your application whenever there is an incoming fax using the number/update_forwarding API.

Note that Fax is only supported in the following countries:

• Singapore
• Hong Kong
• Malaysia

If your account is a trial developer account, you can only receive fax sent from your registered number. To remove this restriction, please make a credit top-up. See Free Trial for details.

API URL:

None

Notifications

You must configure your Hoiio Number to send a notification to your application via either the Developer Portal or number/update_forwarding API. When there is an incoming fax to your Hoiio Number, a notification will be sent to the URL you specified with the following parameters:

Notification Parameters

txn_ref	The unique reference ID for this transaction.
fax_status	Status of the incoming fax. Possible values are: answered failed
from	The sender of this fax. Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.
to	The receiver of this fax (your Hoiio Number). Phone numbers start with a "+" and country code (E.164 format), e.g. +6511111111.
fax_url	You can download the fax in PDF format from this URL. An example of the URL is: https://hoiio.s3.amazonaws.com/infax/fax-1.pdf?Expires=1640069813&AWSAccessKeyId=42GA2R6P2T57JSDQ&Signature=V32sD4hXJb%2Bfh3BFSiy%2Bkg%2F0%3D
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. 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.

API Limits

None.

Charges

Charges apply for fax that are received via this API. The cost per fax is based on your Hoiio number. Please check the Pricing Section for details or you may retrieve the rates with fax/get_rate API.