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:
- Hong Kong
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.
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:
|txn_ref||The unique reference ID for this transaction.|
|fax_status||Status of the incoming fax. Possible values are:
|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:
|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.|
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.
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.