eFax (V2)

This article provides technical guidance for eFax. If you want to learn about how faxing functions in practice, check out this article: Faxing with PetDesk Phones (eFax & Hybrid Fax)

Sending a Fax:

REQUEST: POST https://voice.getkontak.com/api/fax_send.php

• NOTE: All parameters are Case Sensitive and must be in the BODY of the POST, URLENCODED.
• auth is the string of text in the phone system's Advanced menu. It appears to be a lot of nonsense.
• containerID is the 6-digit Container ID number that is present in the top-left corner of the Dashboard when logged into a particular container.
• boxID is the UniqueID of a fax box (also referred to as a UCP Account) within the PBX interface.
• toNumber is the phone number to send the fax to. Please ensure your number is a valid American phone number. The 1 in front of the number is optional. We do not support faxing outside of the USA.
• fileUrl is the URL of the file to be downloaded to send. The file MUST be a PDF. You do not need to URLENCODE this parameter, you can keep all the characters in it as they are.

RESULT: JSON Syntax, either an error string or a success string.

• "success":
  • "faxID" - The unique identifier for this outgoing fax. Save the identifier if you want to query its status later on.
• "error":
  • "Your Container ID is invalid."
  • "Your API Auth Key is invalid."
  • "Your UCP Box ID is invalid."
  • "Destination toNumber is missing."
  • "You must supply a file URL for the eFax server to download."
  • "The file you want to send is not a PDF".
  • "Error connecting to the database. Try again later."
  • "The supplied UCP Box ID either does not exist, or is out of your scope of access."
  • "You cannot fax international destinations."
  • "Something is wrong with the file. It is either not a PDF, or we could not download it."
  • "Unknown issue with database query, could not commit fax to database."

Requesting Fax Status:

REQUEST: GET https://voice.getkontak.com/api/fax_status.php?auth=XXX&containerID=XXX&efaxID=XXX

• NOTE: All parameters are Case Sensitive.
• auth is the string of text in the phone system's Advanced menu. It appears to be a lot of nonsense.
• containerID is the 6-digit Container ID number that is present in the top-left corner of the Dashboard when logged into a particular container.
• efaxID is the UniqueID of a previously uploaded eFax.

RESULT: JSON Syntax, either an error string or a success string.

• "status":
  • "status string/message from eFax system"
• "error":
  • "Your Container ID is invalid."
  • "Your API Auth Key is invalid."
  • "Your supplied eFax ID is invalid."
  • "Error connecting to the database. Try again later."
  • "Unknown issue with database query, could not retrieve fax status."

Fax Webhooks (Incoming & Outgoing):

To set up webhooks, as an Admin, go to UCP Users > Manage, and edit one of your eFax boxes (UCP Accounts). Then click on the EFAX / SMS tab. These settings can also be managed from within a UCP Account, too, when a user is logged in.

• Incoming Fax Webhook Events will be POSTed to your URL whenever a fax is received. The body of the POST will be urlencoded (sorry, no JSON yet) with a download URL for you to retrieve the fax PDF. Fax PDFs are retained for only 30 days.
• Outgoing Fax Status Webhook Events will be POSTed to your URL whenever an outgoing fax changes status. Please review the Possible Responses in the section above, "Requesting Fax Status". The response will be in JSON.
• Important! After setting up webhooks, you must hit the big red APPLY CHANGES button at the top. This is because a reload needs to occur in the phone system dial plan.