API Reference

This defines the Fax API:

  • Request - send an fax.
  • Response - ensure that your request to the Fax API was successful.
  • Webhook - check that your user received your message.

Request

A Fax API request looks like:

https://fax.to/api/v2/fax?api_key=xxxxx&fax_number=xxxxxx&document_id=xxxxxxx

This request contains:

Parameters

The following table shows the parameters you use in the request:

Parameter Description Required
fax_number Fax Number. For example, fax_number=+123456789. Yes.
document_id If you want to use existing document you need to specify the document_id. For example, document_id=10. Yes.
delete_file If you want to delete document after you send a fax then specify the delete_file. For example, delete_file=1. No.
tsi_number If you want to change the text/fax number of sender you need to specify the tsi_number. For example, tsi_number=+12054067065. No.

Authentication information

The following table shows the information for authentication:

Parameter Description Required
api_key Your Key. For example, api_key=f@x2r0ckkz. Yes.

You find your Key in Dashboard.

Security

To ensure privacy, you must use HTTPS for all Faxto API requests.

Encoding

You submit all requests with a POST or GET call using UTF-8 encoding and URL encoded values.

Response

We support JSON ONLY responses


{
  "status": "executed",
  "fax_job_id": 200,
  "user_cash_balance": 100,
  "cost": 0.15
}

Keys and Values

Key Value Response Type
status
Text Meaning
executed The fax job is executed and in the process of sending
failed Failed to send the fax
JSON
fax_job_id The Fax Job ID. You can use the fox_job_id to check the status of the fax job. JSON
user_cash_balance The remaining cash balance JSON
cost The cost of sending fax JSON

Webhook

Notifications are delivered via HTTP POST request to Callback URL you specified in API Settings. Fax.to will be expecting response 200 OK in return, or it will keep retrying every 15 minutes until the Delivery Receipt expires (up to 48 hours) . Fax.to send POST data with the following information:

Key Value
fax_job_id The Fax Job ID
status The Status of the Fax Job. Either success or failed
msg_code
Text Meaning
ok Success! Your fax has been sent!
unknown Fax Failed - Unknown Error ( We don’t know exactly what went wrong - contact us for more info )
no_answer Fax Failed - No Answer from Fax machine
busy Fax Failed - Line Busy ( The fax machine could be busy )
file_error Fax Failed - File conversion failed. Re-upload and Retry
hangup Fax Failed - Early Hangup

Checkout how you can manage the POST data